0% found this document useful (0 votes)

5 views

MOC 2349B - Programming With the Microsoft.net Framework Microsoft Visual C .NET

This document is a delivery guide for the course 'Programming with the Microsoft .NET Framework (Microsoft Visual C# .NET)', intended for experienced software developers. It outlines the course objectives, prerequisites, and a detailed schedule covering various modules related to the .NET Framework, including application development, memory management, and web services. The course aims to equip developers with the skills to effectively use the .NET Framework for building applications.

Uploaded by

eliopires

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

5 views

MOC 2349B - Programming With the Microsoft.net Framework Microsoft Visual C .NET

Uploaded by

eliopires

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 938

Programming with the

Microsoft .NET Framework ®

(Microsoft Visual C# .NET) ™

Delivery Guide
Course Number: 2349B

Part Number: X08-76381

Released: 02/2002
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, places or events is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual
property rights covering subject matter in this document. Except as expressly provided in any
written license agreement from Microsoft, the furnishing of this document does not give you any
license to these patents, trademarks, copyrights, or other intellectual property.

 2001−2002 Microsoft Corporation. All rights reserved.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

Visual Basic, Visual C++, Visual C#, Visual Studio, Win32, Windows, Windows Media, and
Window NT are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A.
and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.

Course Number: 2349B

Part Number: X08-76381
Released: 02/2002
Programming with the Microsoft® .NET Framework (Microsoft Visual C#™ .NET) iii

Contents
Introduction
Introduction..............................................................................................................1
Course Materials ......................................................................................................2
Prerequisites.............................................................................................................3
Course Outline .........................................................................................................4
Microsoft Certified Professional Program ...............................................................9
Facilities.................................................................................................................11
Module 1: Overview of the Microsoft .NET Framework
Overview..................................................................................................................1
Overview of the Microsoft .NET Framework..........................................................2
Overview of Namespaces ......................................................................................13
Review ...................................................................................................................17
Module 2: Introduction to a Managed Execution Environment
Overview..................................................................................................................1
Writing a .NET Application.....................................................................................2
Compiling and Running a .NET Application.........................................................11
Lab 2: Building a Simple .NET Application..........................................................29
Review ...................................................................................................................32
Module 3: Working with Components
Overview..................................................................................................................1
An Introduction to Key .NET Framework Development Technologies ..................2
Creating a Simple .NET Framework Component ....................................................4
Lab 3.1: Creating a .NET Framework Component ................................................11
Creating a Simple Console Client..........................................................................14
Lab 3.2: Creating a Simple Console-Based Client.................................................19
Demonstration: Creating a Windows Forms Client ...............................................22
Creating an ASP.NET Client .................................................................................27
Lab 3.3: Calling a Component Through an ASP.NET Page..................................36
Review ...................................................................................................................40
Module 4: Deployment and Versioning
Overview..................................................................................................................1
Introduction to Application Deployment .................................................................2
Application Deployment Scenarios .........................................................................7
Related Topics and Tools.......................................................................................31
Lab 4: Packaging and Deployment ........................................................................37
Review ...................................................................................................................42
Module 5: Common Type System
Overview..................................................................................................................1
An Introduction to the Common Type System ........................................................2
Elements of the Common Type System...................................................................8
Object-Oriented Characteristics.............................................................................25
Lab 5: Building Simple Types ...............................................................................39
Review ...................................................................................................................44
iv Programming with the Microsoft® .NET Framework (Microsoft Visual C#™ .NET)

Module 6: Working with Types

Overview................................................................................................................. 1
System.Object Class Functionality ......................................................................... 2
Specialized Constructors....................................................................................... 12
Type Operations.................................................................................................... 18
Interfaces............................................................................................................... 28
Managing External Types ..................................................................................... 34
Lab 6: Working with Types .................................................................................. 38
Review .................................................................................................................. 43
Module 7: Strings, Arrays, and Collections
Overview................................................................................................................. 1
Strings ..................................................................................................................... 2
Terminology – Collections.................................................................................... 20
.NET Framework Arrays....................................................................................... 21
.NET Framework Collections ............................................................................... 39
Lab 7: Working with Strings, Enumerators, and Collections................................ 57
Review .................................................................................................................. 63
Module 8: Delegates and Events
Overview................................................................................................................. 1
Delegates................................................................................................................. 2
Multicast Delegates............................................................................................... 12
Events.................................................................................................................... 21
When to Use Delegates, Events, and Interfaces.................................................... 31
Lab 8: Creating a Simple Chat Server................................................................... 32
Review .................................................................................................................. 42
Module 9: Memory and Resource Management
Overview................................................................................................................. 1
Memory Management Basics.................................................................................. 2
Non-Memory Resource Management ................................................................... 12
Implicit Resource Management ............................................................................ 13
Explicit Resource Management ............................................................................ 26
Optimizing Garbage Collection ............................................................................ 36
Lab 9: Memory and Resource Management ......................................................... 49
Review .................................................................................................................. 56
Module 10: Data Streams and Files
Overview................................................................................................................. 1
Streams.................................................................................................................... 2
Readers and Writers ................................................................................................ 5
Basic File I/O .......................................................................................................... 8
Lab 10: Files ......................................................................................................... 21
Review .................................................................................................................. 26
Programming with the Microsoft® .NET Framework (Microsoft Visual C#™ .NET) v

Module 11: Internet Access

Overview..................................................................................................................1
Internet Application Scenarios.................................................................................2
The WebRequest and WebResponse Model............................................................3
Application Protocols.............................................................................................16
Handling Errors......................................................................................................25
Security ..................................................................................................................28
Best Practices.........................................................................................................35
Lab 11: Creating a DateTime Client/Server Application.......................................36
Review ...................................................................................................................41
Course Evaluation..................................................................................................43
Module 12: Serialization
Overview..................................................................................................................1
Serialization Scenarios.............................................................................................2
Serialization Attributes ............................................................................................4
Object Graph............................................................................................................5
Serialization Process ................................................................................................7
Serialization Example ..............................................................................................9
Deserialization Example ........................................................................................10
Custom Serialization..............................................................................................12
Custom Serialization Example...............................................................................14
Security Issues .......................................................................................................17
Lab 12: Serialization ..............................................................................................18
Review ...................................................................................................................27
Module 13: Remoting and XML Web Services
Overview..................................................................................................................1
Remoting..................................................................................................................2
Remoting Configuration Files................................................................................19
Demonstration: Remoting ......................................................................................22
Lab 13.1: Building an Order-Processing Application by Using Remoted Servers 28
XML Web Services................................................................................................36
Lab 13.2: Using an XML Web Service..................................................................48
Review ...................................................................................................................54
Course Evaluation..................................................................................................56
vi Programming with the Microsoft® .NET Framework (Microsoft Visual C#™ .NET)

Optional Modules

Module 14 (Optional): Threading and Asynchronous Programming

Overview................................................................................................................. 1
Introduction to Threading ....................................................................................... 2
Using Threads in .NET ........................................................................................... 9
Thread Safety ........................................................................................................ 29
Special Thread Topics........................................................................................... 51
Asynchronous Programming in .NET................................................................... 74
Lab 14: Working With Multithreaded Applications ............................................. 92
Review ................................................................................................................ 108
Module 15 (Optional): Interoperating Between Managed and
Unmanaged Code
Overview................................................................................................................. 1
Integration Services................................................................................................. 2
Platform Invoke ...................................................................................................... 7
Lab 15.1: Calling Win32 APIs.............................................................................. 16
Calling COM Objects from Managed Code.......................................................... 20
Lab 15.2: Calling COM Objects ........................................................................... 39
Calling .NET Objects from COM Objects............................................................ 43
Review .................................................................................................................. 55
Module 16 (Optional): Using Microsoft ADO.NET to Access Data
Overview................................................................................................................. 1
Overview of ADO.NET .......................................................................................... 2
Connecting to a Data Source................................................................................. 10
Accessing Data with DataSets .............................................................................. 12
Using Stored Procedures....................................................................................... 26
Lab 16: Using ADO.NET to Access Data ............................................................ 34
Accessing Data with DataReaders ........................................................................ 42
Binding to XML Data ........................................................................................... 50
Review .................................................................................................................. 56
Module 17 (Optional): Attributes
Overview................................................................................................................. 1
Overview of Attributes............................................................................................ 2
Defining Custom Attributes .................................................................................. 13
Retrieving Attribute Values .................................................................................. 22
Demonstration: Custom Attributes ....................................................................... 26
Lab 17: Defining and Using Attributes................................................................. 27
Review .................................................................................................................. 36
Programming with the Microsoft® .NET Framework (Microsoft Visual C#™ .NET) vii

About This Course

This section provides you with a brief description of the course, audience,
suggested prerequisites, course objectives, and information about course
customization.

Description
The goal of this five day course is to help application developers understand the
Microsoft® .NET Framework. In addition to offering an overview of the .NET
Framework and an introduction to key concepts and terminology, the course
provides a series of labs, which introduce and explain .NET Framework
features that are used to code, debug, tune, and deploy applications.

Audience
This course is intended for experienced, professional software developers who
work in independent software vendors (ISVs) or work on corporate enterprise
development teams. Most students will be Microsoft Visual C++® (or C++) and
Java developers.

Student Prerequisites
This course requires that students meet the following prerequisites:
• Students should be experienced professional developers and have a basic
understanding of the C# language.
Students can meet the C# language prerequisite by taking Course 2124,
Introduction to C# Programming for the Microsoft .NET Platform.

Course Objectives
After completing this course, the student will be able to:
! List the major elements of the .NET Framework and explain how they fit
into the .NET platform.
! Explain the main concepts behind the common language runtime and use
the features of the .NET Framework to create a simple application.
! Create and use components in Microsoft Windows® Forms-based and
ASP.NET-based applications.
! Use the deployment and versioning features of the .NET runtime to deploy
multiple versions of a component.
! Create, use, and extend types by understanding the Common Type System
architecture.
! Create classes and interfaces that are functionally efficient and appropriate
for specific programming scenarios.
! Use the .NET Framework class library to efficiently create and manage
strings, arrays, collections, and enumerators.
viii Programming with the Microsoft® .NET Framework (Microsoft Visual C#™ .NET)

! Use delegates and events to have an event sender object signal the
occurrence of an action to an event receiver object.
! Describe and control how memory and other resources are managed in the
.NET Framework.
! Read from and write to data streams and files.
! Use the basic request/response model to send and receive data over the
Internet.
! Serialize and deserialize an object graph.
! Create distributed applications through XML Web services and Object
Remoting.
Programming with the Microsoft® .NET Framework (Microsoft Visual C#™ .NET) ix

Day 1
Start End Module
9:00 9:30 Introduction
9:30 10:00 Module 1: Overview of the Microsoft .NET Framework
10:00 10:15 Break
10:15 11:00 Module 2: Introduction to a Managed Execution Environment
11:00 11:15 Lab 2: Building a Simple .NET Application
11:15 11:45 Module 3: Working with Components
11:45 12:00 Lab 3.1: Creating a .NET Framework Component
12:00 1:00 Lunch
1:00 1:15 Module 3: Working with Components (continued)
1:15 1:30 Lab 3.2: Creating a Simple Console-Based Client
1:30 2:00 Module 3: Working with Components (continued)
2:00 2:30 Lab 3.3: Calling a Component Through an ASP .NET Page
2:30 2:45 Break
2:45 4:15 Module 4: Deployment and Versioning

Day 2
Start End Module
9:00 9:50 Lab 4: Packaging and Deployment
9:50 10:00 Break
10:00 11:30 Module 5: Common Type System
11:30 12:30 Lunch
12:30 1:15 Lab 5: Building Simple Types
1:15 2:30 Module 6: Working with Types
2:30 2:45 Break
2:45 3:30 Lab 6: Working with Types
3:30 4:00 Module 7: Strings, Arrays, and Collections
x Programming with the Microsoft® .NET Framework (Microsoft Visual C#™ .NET)

Day 3
Start End Module
9:00 10:30 Module 7: Strings, Arrays, and Collections (continued)
10:30 10:45 Break
10:45 11:45 Lab 7: Working with Strings, Enumerators, and Collections
11:45 12:45 Lunch
12:45 2:00 Module 8: Delegates and Events
2:00 2:15 Break
2:15 3:30 Lab 8: Creating a Simple Chat Server
3:30 4:00 Module 9: Memory and Resource Management

Day 4
Start End Module
9:00 10:30 Module 9: Memory and Resource Management (continued)
10:30 10:45 Break
10:45 11:45 Lab 9: Memory and Resource Management
11:45 12:45 Lunch
12:45 1:30 Module 10: Data Streams and Files
1:30 2:15 Lab 10: Files
2:15 2:30 Break
2:30 3:30 Module 11: Internet Access
3:30 4:15 Lab 11: Creating a DateTime Client/Server Application

Day 5
Start End Module
9:00 9:30 Module 12: Serialization
9:30 10:15 Lab 12: Serialization
10:15 10:30 Break
10:30 11:30 Module 13: Remoting and Web Services
11:30 12:30 Lunch
12:30 1:20 Lab 13.1: Building an Order-Processing Application by Using
Remoted Servers
1:20 2:20 Module 13: Remoting and Web Services (continued)
2:20 2:35 Break
2:35 3:30 Lab 13.2: Using an XML Web Service
Programming with the Microsoft® .NET Framework (Microsoft Visual C#™ .NET) xi

Trainer Materials Compact Disc Contents

The Trainer Materials compact disc contains the following files and folders:
! Autorun.exe. When the compact disc is inserted into the compact disc drive,
or when you double-click the Autorun.exe file, this file opens the compact
disc and allows you to browse the Student Materials or Trainer Materials
compact disc.
! Autorun.inf. When the compact disc is inserted into the compact disc drive,
this file opens Autorun.exe.
! Default.htm. This file opens the Trainer Materials Web page.
! Readme.txt. This file explains how to install the software for viewing the
Trainer Materials compact disc and its contents and how to open the Trainer
Materials Web page.
! 2349B_ms.doc. This file is the Manual Classroom Setup Guide. It contains
the steps for manually setting up the classroom computers.
! 2349B_sg.doc. This file is the Automated Classroom Setup Guide. It
contains a description of classroom requirements, classroom configuration,
instructions for using the automated classroom setup scripts, and the
Classroom Setup Checklist.
! Powerpnt. This folder contains the Microsoft PowerPoint® slides that are
used in this course.
! Pptview. This folder contains the Microsoft PowerPoint Viewer, which is
used to display the PowerPoint slides.
! Setup. This folder contains the files that install the course and related
software to computers in a classroom setting.
! StudentCD. This folder contains the Web page that provides students with
links to resources pertaining to this course, including additional reading,
review and lab answers, lab files, multimedia presentations, and course-
related Web sites.
! Tools. This folder contains files and utilities used to complete the setup of
the instructor computer.
! Webfiles. This folder contains the files that are required to view the course
Web page. To open the Web page, open Windows Explorer, and in the root
directory of the compact disc, double-click Default.htm or Autorun.exe.
xii Programming with the Microsoft® .NET Framework (Microsoft Visual C#™ .NET)

Student Materials Compact Disc Contents

The Student Materials compact disc contains the following files and folders:
! Autorun.exe. When the compact disc is inserted into the CD-ROM drive, or
when you double-click the Autorun.exe file, this file opens the compact
disc and allows you to browse the Student Materials compact disc.
! Autorun.inf. When the compact disc is inserted into the compact disc drive,
this file opens Autorun.exe.
! Default.htm. This file opens the Student Materials Web page. It provides
students with resources pertaining to this course, including additional
reading, review and lab answers, lab files, multimedia presentations, and
course-related Web sites.
! Readme.txt. This file explains how to install the software for viewing the
Student Materials compact disc and its contents and how to open the
Student Materials Web page.
! 2349B_ms.doc. This file is the Manual Classroom Setup Guide. It contains a
description of classroom requirements, classroom setup instructions, and the
classroom configuration.
! Democode. This folder contains demonstration code.
! Flash. This folder contains the installer for the Macromedia Flash 5.0
browser plug-in.
! Fonts. This folder contains fonts that are required to view the PowerPoint
presentation and Web-based materials.
! Labs. This folder contains files that are used in the hands-on labs. These
files may be used to prepare the student computers for the hands-on labs.
! Media. This folder contains files that are used in multimedia presentations
for this course.
! Mplayer. This folder contains the setup file to install Microsoft Windows
Media™ Player.
! Webfiles. This folder contains the files that are required to view the course
Web page. To open the Web page, open Windows Explorer, and in the root
directory of the compact disc, double-click Default.htm or Autorun.exe.
! Wordview. This folder contains the Word Viewer that is used to view any
Word document (.doc) files that are included on the compact disc.
Programming with the Microsoft® .NET Framework (Microsoft Visual C#™ .NET) xiii

Document Conventions
The following conventions are used in course materials to distinguish elements
of the text.
Convention Use

" Indicates an introductory page. This symbol appears next

to a topic heading when additional information on the topic
is covered on the page or pages that follow it.
bold Represents commands, command options, and syntax that
must be typed exactly as shown. It also indicates
commands on menus and buttons, dialog box titles and
options, and icon and menu names.
italic In syntax statements or descriptive text, indicates argument
names or placeholders for variable information. Italic is
also used for introducing new terms, for book and course
titles, and for emphasis in the text.
Title Capitals Indicate domain names, user names, computer names,
directory names, and folder and file names, except when
specifically referring to case-sensitive names. Unless
otherwise indicated, you can use lowercase letters when
you type a directory name or file name in a dialog box or
at a command prompt.
ALL CAPITALS Indicate the names of keys, key sequences, and key
combinations — for example, ALT+SPACEBAR.
monospace Represents code samples or examples of screen text.
[] In syntax statements, enclose optional items. For example,
[filename] in command syntax indicates that you can
choose to type a file name with the command. Type only
the information within the brackets, not the brackets
themselves.
{} In syntax statements, enclose required items. Type only the
information within the braces, not the braces themselves.
| In syntax statements, separates an either/or choice.
! Indicates a procedure with sequential steps.
... In syntax statements, specifies that the preceding item may
be repeated.
. Represents an omitted portion of a code sample.
.
.
THIS PAGE INTENTIONALLY LEFT BLANK
Introduction

Contents

Introduction 1
Course Materials 2
Prerequisites 3
Course Outline 4
Microsoft Certified Professional Program 9
Facilities 11
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, place or event is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

 2001-2002 Microsoft Corporation. All rights reserved.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Introduction iii

Instructor Notes
Presentation: The Introduction module provides students with an overview of the course
30 Minutes content, materials, and logistics for Course 2349B, Programming with the
Microsoft® .NET Framework (Microsoft Visual C#™ .NET).

Course Materials and Preparation

Required Materials
To teach this course, you need the following materials:
! Delivery Guide
! Trainer Materials compact disc

Preparation Tasks
To prepare for this course, you must complete the Course Preparation Checklist
that is included with the trainer course materials.

Module Strategy
Use the following strategy to present this module:
! Course 2349B, Programming with the Microsoft .NET Framework
(Microsoft Visual C# .NET)
Show the slide that displays the course number and course title.
! Introduction
Welcome students to the course and introduce yourself. Provide a brief
overview of your background to establish credibility.
Have students introduce themselves and provide their background, product
experience, and expectations of the course.
Record student expectations on a white board or flip chart that you can
reference later in class.
! Course Materials
Explain the purpose of all materials used in this course.
! Prerequisites
Provide the students with the list of prerequisites that they should have met
before taking this course. This is an opportunity for you to identify students
who may not have the appropriate background or experience to attend this
course.
iv Introduction

! Course Outline
Provide an overview of each module and what students will learn.
Explain how this course will meet students’ expectations by relating the
information covered in individual modules to their expectations.
Providing reasonably complete coverage of the Microsoft .NET Framework
within a five day class is a challenging undertaking. The thirteen modules
that encompass Course 2349B, Programming with the Microsoft.NET
Framework (Microsoft Visual C# .NET), will provide most students with a
common baseline for working with the .NET Framework.

Note For more information about customizing this course see the Optional
Course Presentation Strategies section in this module.

! Setup
Provide the students with any necessary setup information for the course.
! Microsoft Certified Professional Program
Inform students about the Microsoft Certified Professional (MCP) program
and the various certification options.
! Facilities
Explain the facility information for the training site.
Introduction v

Optional Course Presentation Strategies

Because of the complexity and amount of material that makes up the .NET
Framework, additional resources are included to provide instructors with some
flexibility in the course delivery.

Course Customization
The thirteen modules that make up the five day Course 2349B, Programming
with the Microsoft .NET Framework (Microsoft Visual C# .NET), will provide
most students with a common baseline for working with the .NET Framework.
In addition to the first thirteen modules that make up the five days of material,
the course contains four optional modules, thus providing you with the
opportunity for customization.
You are not required to cover the optional modules as part of Course 2349B,
Programming with the Microsoft .NET Framework (Microsoft Visual C# .NET).
The decision about whether to cover the optional modules has been left entirely
to you, the instructor, as you will need to consider the circumstances of each
class separately, including student levels and preferences, and any requirements
of an individual Microsoft Certified Technical Education Center (Microsoft
CTEC).
However, as part of the course materials, your students will receive all
seventeen modules. While Modules 14 through 17 are considered optional, you
should be prepared to discuss what you plan to cover during the course
introduction. If you only intend to cover the first thirteen modules that make up
the official five days of course delivery of Course 2349B, Programming with
the Microsoft .NET Framework (Microsoft Visual C# .NET), then state that
clearly and suggest that the optional modules may be used as additional self-
study. Alternatively, you may want to discuss covering one or more of the
optional modules if there is sufficient interest in those topics. You will then
need to consider with your students what module(s) you may safely leave out in
order to accommodate the optional module(s).
For example, an alternative approach for more advanced students who already
have a basic understanding of .NET Framework applications and the Microsoft
Visual C#™ .NET object model would be to omit Modules 2 through 6 and
teach Modules 7 through 17.
vi Introduction

Course Flow
As a general guideline, modules may be grouped accordingly, as shown in the
following table.
Module Course Flow

Module 1: Overview of the Microsoft This short module is designed to provide a

.NET Framework high level overview of the .NET
Framework.
Module 2: Introduction to a Managed Modules 2 through 4 cover core .NET
Execution Environment Framework concepts, including managed
Module 3: Working with Components execution, assemblies, and deployment.

Module 4: Deployment and Versioning

Module 5: Common Type System Modules 5 and 6 cover core .NET
Module 6: Working with Types Framework object oriented topics.

Module 7: Strings, Arrays, and Modules 7 through 13 cover more

Collections advanced material than the preceding
Module 8: Delegates and Events modules and may be considered as
standalone material. Modules 10 through
Module 9: Memory and Resource 12 have some relevance to Module 13:
Management Remoting and XML Web Services.
Module 10: Data Streams and Files
Module 11: Internet Access
Module 12: Serialization
Module 13: Remoting and XML Web
Services
Module 14: Threading and Asynchronous Modules 14 through 17 may be considered
Programming as optional, standalone, and generally
Module 15: Interoperating Between more advanced than modules 1 through 6.
Managed and Unmanaged Code
Module 16: Using Microsoft ADO.NET to
Access Data
Module 17: Attributes
Introduction vii

Course Timing
This section provides estimated course timings for all of the modules, labs, and
breaks in Course 2349B, Programming with the Microsoft .NET Framework
(Microsoft Visual C# .NET). The following schedule options are provided as a
guide to help with ideas about how to organize your class if you decide to
customize the course.

Option 1
The following schedule is an estimate of the course timing if you choose to
teach Modules 1 through 13. This is the basic approach for students needing
additional instruction regarding Visual C# .NET and the .NET Framework
approach to assemblies, packaging and the object model. If you do not intend to
customize Course 2349B, Programming with the Microsoft .NET Framework
(Microsoft Visual C# .NET), this is the approach you should use. Your timing
may vary.

Option 2
The following schedule is an estimate of the course timing if you choose to
teach Module 1 followed by Modules 7 through 17. This approach would serve
more advanced students who already have a solid understanding of Visual C#
.NET and the .NET Framework approach to assemblies, packaging and the
object model. Your timing may vary.

Day 1
Start End Module
9:00 9:30 Introduction
9:30 10:00 Module 1: Overview of the Microsoft .NET Framework
10:00 10:15 Break
10:15 11:45 Module 7: Strings, Arrays, and Collections
11:45 12:45 Lunch
12:45 1:15 Module 7: Strings, Arrays, and Collections (continued)
1:15 2:15 Lab 7: Working with Strings, Enumerators, and Collections
2:15 2:30 Break
2:30 3:55 Module 8: Delegates and Events
3:55 4:15 Break
4:15 5:15 Lab 8: Creating a Simple Chat Server

Day 2
Start End Module
9:00 10:30 Module 9: Memory and Resource Management
10:30 10:45 Break
10:45 11:20 Module 9: Memory and Resource Management (continued)
11:20 11:50 Lab 9: Memory and Resource Management
11:50 1:00 Lunch
1:00 1:30 Lab 9: Memory and Resource Management (continued)
1:30 2:15 Module 10: Data Streams and Files
2:15 3:00 Lab 10: Files
3:00 3:15 Break
3:15 4:15 Module 11: Internet Access
4:15 5:00 Lab 11: Creating a DateTime Client/Server Application
x Introduction

Day 3
Start End Module
9:00 9:30 Module 12: Serialization
9:30 10:15 Lab 12: Serialization
10:15 10:30 Break
10:30 11:30 Module 13: Remoting and XML Web Services
11:30 12:30 Lunch
12:30 1:20 Lab 13.1: Building an Order-Processing Application by Using
Remoted Servers
1:20 2:20 Module 13: Remoting and XML Web Services (continued)
2:20 2:35 Break
2:35 3:30 Lab 13.2: Using an XML Web Service

Day 4
Start End Module
9:00 10:15 Module 14: Threading and Asynchronous Programming
10:15 10:30 Break
10:30 11:45 Module 14: Threading and Asynchronous Programming
(continued)
11:45 12:45 Lunch
12:45 1:45 Lab 14: Working with Multithreaded Applications
1:45 2:00 Break
2:00 2:45 Module 15: Interoperating Between Managed and Unmanaged
Code
2:45 3:15 Lab 15.1: Calling Win32 APIs
3:15 3:30 Break
3:30 4:15 Module 15: Interoperating Between Managed and Unmanaged
Code (continued)
4:15 4:45 Lab 15.2: Calling COM Objects

Day 5
Start End Module
9:00 10:30 Module 16: Using Microsoft ADO.NET to Access Data
10:30 10:45 Break
10:45 11:15 Module 16: Using Microsoft ADO.NET to Access Data
(continued)
11:15 12:15 Lab 16: Using ADO.NET to Access Data
12:15 1:15 Lunch
1:15 2:15 Module 17: Attributes
2:15 2:30 Break
2:30 3:15 Lab 17: Defining and Using Attributes
Introduction xi

Other Options
The standard approach could be further customized by substituting one or more
of Modules 7 through 13 with Modules 14 through 17. In addition, a more
advanced option of delivery would be to extend the course by offering all
seventeen modules. However, the decision to offer this delivery option would
need to be reached in accordance with the policies and business requirements of
individual Microsoft Certified Technical Education Centers (Microsoft
CTECs).
The following table lists the times for individual labs and modules.
Lecture Time Lab Time Lecture and Lab
Module Title (only) (only) Time (combined)

Module 1: Overview of the Microsoft .NET 30 minutes None 30 minutes

Framework
Module 2: Introduction to a Managed Execution 45 minutes 20 minutes 65 minutes
Environment
Module 3: Working with Components 70 minutes 60 minutes 130 minutes
Module 4: Deployment and Versioning 90 minutes 50 minutes 140 minutes
Module 5: Common Type System 90 minutes 45 minutes 130 minutes
Module 6: Working with Types 75 minutes 45 minutes 125 minutes
Module 7: Strings, Arrays, and Collections 120 minutes 60 minutes 180 minutes
Module 8: Delegates and Events 75 minutes 75 minutes 150 minutes
Module 9: Memory and Resource Management 120 minutes 60 minutes 180 minutes
Module 10: Data Streams and Files 45 minutes 45 minutes 90 minutes
Module 11: Internet Access 60 minutes 45 minutes 105 minutes
Module 12: Serialization 30 minutes 45 minutes 75 minutes
Module 13: Remoting and XML Web Services 120 minutes 105 minutes 225 minutes
Module 14: Threading and Asynchronous 150 minutes 60 minutes 210 minutes
Programming
Module 15: Interoperating Between Managed and 90 minutes 60 minutes 150 minutes
Unmanaged Code
Module 16: Using Microsoft ADO.NET to Access 120 minutes 60 minutes 180 minutes
Data
Module 17: Attributes 60 minutes 45 minutes 105 minutes
Introduction 1

Introduction
Topic Objective
To introduce yourself,
establish credibility, meet ! Name
students, and set student
expectations for the course. ! Company Affiliation
Lead-in ! Title/Function
Good morning. Welcome to
Course 2349B, ! Job Responsibility
Programming with the
Microsoft .NET Framework ! Programming Experience
(Microsoft Visual C# .NET).
! .NET Framework Experience
My name is...
! Expectations for the Course

*ILLEGAL FOR NON-TRAINER USE**

Introduce yourself.

Provide a brief overview of

your background to
establish credibility as a
.NET Framework instructor.

Ask students to introduce

themselves, addressing the
bulleted items on the slide.
Delivery Tip
As students introduce
themselves, use a white
board or flip chart to record
their expectations of the
course.
2 Introduction

Course Materials
Topic Objective
To identify and describe the
course materials.
! Name Card
Lead-in
We have provided ! Student Workbook
everything you need for this
course. You will find the ! Student Materials Compact Disc
following materials at your
desk... ! Course Evaluation

*ILLEGAL FOR NON-TRAINER USE**

Describe the contents of the The following materials are included with your kit:
student workbook and the
Student Materials compact ! Name card. Write your name on both sides of the name card.
disc. ! Student workbook. The student workbook contains the material covered in
class, in addition to the hands-on lab exercises.
Have students write their
names on both sides of the ! Student Materials compact disc. The Student Materials compact disc
name card. contains the Web page that provides you with links to resources pertaining
to this course, including additional readings, review and lab answers, lab
Tell students where they files, multimedia presentations, and course-related Web sites.
can send comments with
feedback on the course.
Note To open the Web page, insert the Student Materials compact disc into
Delivery Tip the CD-ROM drive, and then in the root directory of the compact disc,
Demonstrate how to open double-click Autorun.exe or Default.htm.
the Web page provided on
the Student Materials
compact disc. On the ! Course evaluation. To provide feedback on the course, training facility, and
Trainer Materials compact instructor, you will have the opportunity to complete an online evaluation
disc, double-click near the end of the course.
Autorun.exe or
To provide additional comments or inquire about the Microsoft Certified
Default.htm in the
StudentCD folder.
Professional program, send e-mail to [email protected].
Introduction 3

Prerequisites
Topic Objective
To present and describe the
prerequisites for this course.
! Proficiency in the C++ or Java Programming Languages
Lead-in
The following prerequisite ! A basic understanding of the C# Language
knowledge is needed for this
course.

*ILLEGAL FOR NON-TRAINER USE**

This course requires that you meet the following prerequisites:
! Proficiency in the C++ or Java programming languages
! A basic understanding of the C# language
Students can meet the C# language prerequisite by taking Course 2124,
Introduction to C# Programming for the Microsoft .NET Platform.
4 Introduction

Course Outline
Topic Objective
To provide an overview of
each module and what
students will learn. ! Module 1: Overview of the Microsoft .NET Framework
Lead-in ! Module 2: Introduction to a Managed Execution
In this course, we will Environment
cover...
! Module 3: Working with Components
! Module 4: Deployment and Versioning
! Module 5: Common Type System
! Module 6: Working with Types

*ILLEGAL FOR NON-TRAINER USE**

Briefly describe each Module 1, “Overview of the Microsoft .NET Framework,” defines terminology
module. specific to the Microsoft® .NET Framework and describes its key features and
benefits. This module also discusses the namespaces taught in this course.
As you describe each There will be minimal lecture and no lab. After completing this module, you
module, acknowledge any will be able to list the major elements of the .NET Framework.
information that will meet
the student expectations Module 2, “Introduction to a Managed Execution Environment,” introduces the
that you recorded earlier. concept of managed execution and shows developers how to quickly build
applications that take advantage of the new .NET Framework common
language runtime environment. After completing this module, you will be able
to explain the main concepts behind the common language runtime and use the
features of the .NET Framework to create a simple application.
Module 3, “Working with Components,” discusses how to create a small,
componentized application where modules can easily be written in either
Microsoft Visual C#™ or Microsoft Visual Basic®. The steps necessary to
construct, compile, and run each program are covered in detail. This module
also explains how to build the client application by using the Microsoft
Windows® Forms library and ASP.NET Web Forms. After completing this
module, you will be able to create and use components in Windows Forms-
based and ASP.NET-based applications.
Module 4, “Deployment and Versioning,” explains how to use deployment and
versioning features of the .NET Framework common language runtime to build
and deploy applications that are fully managed and protected. After completing
this module, you will be able to use the deployment and versioning features of
the .NET Framework common language runtime to deploy multiple versions of
a component.
Introduction 5

Module 5, “Common Type System,” introduces the Common Type System.

The module discusses how to differentiate between value types and reference
types and examines how classes, interfaces, properties, methods, events, and
values are represented in the .NET Framework. After completing this module,
you will be able to create, use, and extend types by understanding the Common
Type System architecture.
Module 6, “Working with Types,” discusses the use of attributes to control
visibility and inheritance on types and explains how to work with various type
operations, such as boxing and unboxing, and type operators. In addition, this
module discusses how to build an interface that supports methods and
properties and how to make interface designs more efficient. Finally, this
module highlights features that are designed to help you work with unmanaged
types, such as COM types. After completing this module, you will be able to
create classes and interfaces that are functionally efficient and appropriate for
specific programming scenarios.
6 Introduction

Course Outline (continued)

! Module 7: Strings, Arrays, and Collections

! Module 8: Delegates and Events
! Module 9: Memory and Resource Management
! Module 10: Data Streams and Files
! Module 11: Internet Access
! Module 12: Serialization
! Module 13: Remoting and XML Web Services

*ILLEGAL FOR NON-TRAINER USE**

Module 7, “Strings, Arrays, and Collections,” describes some of the key classes
in the .NET Framework class library. This module explains how to work with
strings, arrays, collections, and enumerators. After completing this module, you
will be able to use the .NET Framework class library to efficiently create and
manage strings, arrays, collections, and enumerators.
Module 8, “Delegates and Events,” explains how the .NET Framework uses
delegates in callback and event-handling scenarios. After completing this
module, you will be able to use delegates and events to have an event sender
object signal the occurrence of an “action” to an event receiver object.
Module 9, “Memory and Resource Management,” discusses how the .NET
Framework automatically handles the allocation and release of an object’s
memory resources through garbage collection. After completing this module,
you will be able to describe and control how memory and other resources are
managed in the .NET Framework.
Module 10, “Data Streams and Files,” introduces the System.IO namespace
and discusses the types that it contains that allow synchronous and
asynchronous reading from and writing to data streams and files. This module
discusses synchronous operations only, as asynchronous operations are beyond
the scope of this course. After completing this module, you will be able to read
from and write to data streams and files.
Module 11, “Internet Access,” discusses the use of the System.Net classes to
communicate with other applications by using common protocols, such as
HTTP, Transmission Control Protocol (TCP), User Datagram Protocol (UDP),
and Socket Internet protocols. After completing this module, you will be able to
use the basic request/response model to send and receive data over the Internet.
Introduction 7

Module 12, “Serialization,” explains how to use serialization to convert a graph

of objects into a linear sequence of bytes, which can then be sent to a remote
computer and deserialized, thereby making a clone in the remote memory of the
original graph of objects. After completing this module, you will be able to
serialize and deserialize an object graph.
Module 13, “Remoting and XML Web Services,” explains how .NET Remoting
supports communication between objects in different application domains, in
different processes, and on different computers. The module describes how the
common language runtime remoting infrastructure provides a rich set of classes
that enable you to ignore most of the complexities of deploying and managing
remote objects. After completing this module, you will be able to create
distributed applications by means of XML Web services and Object Remoting.
8 Introduction

Course Outline (continued)

! Module 14 (Optional): Threading and Asynchronous

Programming
! Module 15 (Optional): Interoperating Between Managed
and Unmanaged Code
! Module 16 (Optional): Using Microsoft ADO.NET to
Access Data
! Module 17 (Optional): Attributes

*ILLEGAL FOR NON-TRAINER USE**

The following modules are optional and can also be used as further reading
about .NET Framework topics.
Module 14, “Threading and Asynchronous Programming,” covers the support
that the Microsoft .NET Framework provides for working with multithreaded
applications and asynchronous programming. After completing this module, in
addition to creating and managing threads, you will be able to handle thread
synchronization to maintain application responsiveness and avoid potential data
corruption and other problems.
Module 15, “Interoperating between Managed and Unmanaged Code,”
introduces the services that are provided by the .NET Framework to allow
managed code to interoperate with unmanaged code. After completing this
module, you will be able to use Platform Invoke to call unmanaged functions
that are implemented in a DLL. You will also be able to call COM objects from
managed code.
Module 16, “Using Microsoft ADO.NET to Access Data,” presents ADO.NET
as an evolution of the ADO data access model, with a rich suite of data
handling and data binding functions for manipulating all types of data. After
completing this module, you will use the rapid application design facilities of
Microsoft Visual Studio® .NET to create an XML Web service whose methods
can be used to read and update a database by using ADO.NET. You will also
Use Visual Studio.NET rapid application design facilitates to create a Windows
Forms application that displays and enables a user to update a DataGrid
control that is bound to a DataSet. The DataSet is obtained and updated by
using an XML Web service.
Module 17, “Attributes,” provides details about how to use attributes in code. It
describes the predefined attributes that are provided by the Microsoft .NET
Framework and provides some simple examples of how to use some common
attributes. After completing this module, you will be able to use custom
predefined attributes, create simple custom attributes, and query attribute
information at run time.
Introduction 9

Microsoft Certified Professional Program

Topic Objective
To provide students with
information about the
Microsoft Certified
Professional Program.
Lead-in
The Microsoft Certified
Professional Program
includes these
certifications…

http://www.microsoft.com/traincert/

*ILLEGAL FOR NON-TRAINER USE**

The Microsoft Certified Professional program is a leading certification program
that validates your experience and skills to keep you competitive in today’s
changing business environment. The following table describes each certification
in more detail.
Certification Description

MCSA on Microsoft The Microsoft Certified Systems Administrator (MCSA) certification is designed for
Windows 2000 professionals who implement, manage, and troubleshoot existing network and system
environments based on Microsoft Windows 2000 platforms, including the Windows
.NET Server family. Implementation responsibilities include installing and configuring
parts of the systems. Management responsibilities include administering and supporting
the systems.
MCSE on Microsoft The Microsoft Certified Systems Engineer (MCSE) credential is the premier
Windows 2000 certification for professionals who analyze the business requirements and design
and implement the infrastructure for business solutions based on the Microsoft
Windows 2000 platform and Microsoft server software, including the Windows .NET
Server family. Implementation responsibilities include installing, configuring, and
troubleshooting network systems.
MCSD The Microsoft Certified Solution Developer (MCSD) credential is the premier
certification for professionals who design and develop leading-edge business solutions
with Microsoft development tools, technologies, platforms, and the Microsoft Windows
DNA architecture. The types of applications MCSDs can develop include desktop
applications and multi-user, Web-based, N-tier, and transaction-based applications. The
credential covers job tasks ranging from analyzing business requirements to maintaining
solutions.
10 Introduction

(continued)
Certification Description

MCDBA on Microsoft The Microsoft Certified Database Administrator (MCDBA) credential is the premier
SQL Server 2000 certification for professionals who implement and administer Microsoft SQL Server™
databases. The certification is appropriate for individuals who derive physical database
designs, develop logical data models, create physical databases, create data services by
using Transact-SQL, manage and maintain databases, configure and manage security,
monitor and optimize databases, and install and configure SQL Server.
MCP The Microsoft Certified Professional (MCP) credential is for individuals who have the
skills to successfully implement a Microsoft product or technology as part of a business
solution in an organization. Hands-on experience with the product is necessary to
successfully achieve certification.
MCT Microsoft Certified Trainers (MCTs) demonstrate the instructional and technical skills
that qualify them to deliver Microsoft Official Curriculum through Microsoft Certified
Technical Education Centers (Microsoft CTECs).

Certification Requirements
The certification requirements differ for each certification category and are
specific to the products and job functions addressed by the certification. To
become a Microsoft Certified Professional, you must pass rigorous certification
exams that provide a valid and reliable measure of technical proficiency and
expertise.

For More Information See the Microsoft Training and Certification Web site at
http://www.microsoft.com/traincert.
You can also send e-mail to [email protected] if you have specific
certification questions.

Acquiring the Skills Tested by an MCP Exam

Microsoft Official Curriculum (MOC) and MSDN® Training Curriculum can
help you develop the skills that you need to do your job. They also complement
the experience that you gain while working with Microsoft products and
technologies. However, no one-to-one correlation exists between MOC and
MSDN Training courses and MCP exams. Microsoft does not expect or intend
for the courses to be the sole preparation method for passing MCP exams.
Practical product knowledge and experience is also necessary to pass the MCP
exams.
To help prepare for the MCP exams, use the preparation guides that are
available for each exam. Each Exam Preparation Guide contains exam-specific
information, such as a list of the topics on which you will be tested. These
guides are available on the Microsoft Training and Certification Web site at
http://www.microsoft.com/traincert/.
Introduction 11

Facilities
Topic Objective
To inform students of class Class Hours
logistics and rules for the
training site.
Building Hours Phones
Lead-in
Before we start, let’s go over
the class logistics.
Parking Messages

Rest Rooms Smoking

Meals Recycling

*ILLEGAL FOR NON-TRAINER USE**

Explain the class hours,

extended building hours for
labs, parking, rest room
location, meals, phones,
message posting, and
where smoking is or isn’t
allowed.

Let students know if your

facility has Internet access
that is available for them to
use during class breaks.

Also make sure that the

students are aware of the
recycling program if one is
available.
THIS PAGE INTENTIONALLY LEFT BLANK
Module 1: Overview of
the Microsoft .NET
Framework
Contents

Overview 1
Overview of the Microsoft .NET Framework 2
Overview of Namespaces 13
Review 17
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, place or event is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

 2001-2002 Microsoft Corporation. All rights reserved.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Module 1: Overview of the Microsoft .NET Framework iii

Instructor Notes
Presentation: This module provides students with an overview of the Microsoft® .NET
30 Minutes Framework. It defines some of the terminology that is specific to the .NET
Framework and describes the key features and benefits of the .NET Framework.
Lab:
00 Minutes The module starts with an overview of the .NET Framework, and then
introduces the namespaces in the .NET Framework. It explains which modules
teach which namespaces, and which namespaces are not covered in this course.
Do not spend too much time on this module. This module is designed to
provide only an overview, so do not go into too much detail.
This module contains no labs.
After completing this module, students will be able to:
! Describe the .NET Framework and its components.
! Explain the relationship between the .NET Framework class library and
namespaces.

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach
this module.

Required Materials
To teach this module, you need the Microsoft PowerPoint® file 2349B_01.ppt.

Preparation Tasks
To prepare for this module, you should read all of the materials for this module.
iv Module 1: Overview of the Microsoft .NET Framework

Module Strategy
Use the following strategy to present this module:
! The .NET Framework
Explain each part of the .NET Framework. One important goal of this slide
is to explain what this course covers. This course primarily teaches the
common language runtime and the .NET Framework class library. This
course uses Microsoft Visual C#™ to teach the .NET Framework. Only
minimal coverage of XML Web services, user interfaces, ADO.NET, and
ASP.NET is provided. Other courses will cover these technologies in more
detail. In addition, ADO.NET is covered more fully in Module 16, “Using
Microsoft ADO.NET to Access Data,” in Course 2349B, Programming with
the Microsoft .NET Framework (Microsoft Visual C# .NET).
! Common Language Runtime
This is a build slide. Explain each of the following topics as they appear.
Definitions of these topics are found in the content.
• Class Loader
• Microsoft Intermediate Language (MSIL) to Native compilers, Code
Manager, and Garbage Collection
• Security Engine, Debugger, Type Checker, Exception Manager, Thread
Support, and COM Marshaler
• .NET Framework Class Library Support
! The .NET Framework Class Library
Explain the benefits of the .NET Framework class library. Explain that the
common type system is covered in more detail in Module 5, “Common
Type System,” and Module 6, “Working with Types,” in Course 2349B,
Programming with the Microsoft .NET Framework (Microsoft Visual C#
.NET). Specific classes are covered in Module 7, “Strings, Arrays, and
Collections,” and other modules as appropriate.
! ADO.NET: Data and XML
This is a build slide. Explain the following topics as they appear.
• System.Data
Explain how this namespace works primarily with data, such as data
from databases.
• System.Xml
Explain how this namespace works primarily with XML and Extensible
Stylesheet Language (XSL).
Module 1: Overview of the Microsoft .NET Framework v

! What Is an XML Web Service?

This slide is the key slide for explaining XML Web services. Be sure that
everyone understands the role of Web Services Description Language
(WSDL), Universal Description, Discovery, and Integration (UDDI),
SOAP, XML, and HTTP. Also explain that the .NET software development
kit (SDK) and Microsoft Visual Studio® .NET provide tools to simplify the
creation of XML Web services.
Note that XML Web services are appropriate for internal applications in
addition to external applications. An organization is likely to run multiple
platforms; XML Web services are a good way of working across platforms
because they rely on XML and SOAP. Any platform that supports XML and
SOAP can use or expose XML Web services.
! Web Forms and XML Web Services
Explain how ASP.NET classes make it easier to work with user data on
Web pages.
! Namespaces
Briefly explain the purpose of each namespace. The key point to explain is
that there are a lot of data types and functionality in the .NET Framework.
Namespaces arrange the types in a hierarchy that make it easier to work
with the types.
! Namespaces Used in this Course
Briefly explain which modules teach which namespaces. Explain that not all
of the namespaces are taught in their entirety. For example, the
System.Reflection namespace is mentioned in Module 4, “Deployment and
Versioning,” in Course 2349B, Programming with the Microsoft .NET
Framework (Microsoft Visual C# .NET), only in terms of versioning.
System.Reflection is also mentioned in Module 17, “Attributes,” in Course
2349B, Programming with the Microsoft .NET Framework (Microsoft
Visual C# .NET).
Also, explain that the ADO.NET namespace is covered more fully in
Module 16, “Using Microsoft ADO.NET to Access Data,” in Course
2349B, Programming with the Microsoft .NET Framework (Microsoft
Visual C# .NET).
The security namespace is not taught in this course as security is covered
extensively in Course 2350A, Securing and Deploying Microsoft .NET
Assemblies.
Module 1: Overview of the Microsoft .NET Framework 1

Overview
Topic Objective
To provide an overview of
the module topics and
objectives.
! Overview of the Microsoft .NET Framework
Lead-in ! Overview of Namespaces
In this module, you will be
introduced to the .NET
Framework. You will then
learn about the namespaces
and which modules teach
certain namespaces.

*ILLEGAL FOR NON-TRAINER USE**

The Microsoft® .NET Framework provides tools and technologies that you need
to build distributed Web applications. In this module, you will learn the
architecture of the .NET Framework. You will also learn how the .NET
Framework class library is divided into namespaces, and which namespaces are
taught in this course.
After completing this module, you will be able to:
! Describe the .NET Framework and its components.
! Explain the relationship between the .NET Framework class library and
namespaces.
2 Module 1: Overview of the Microsoft .NET Framework

" Overview of the Microsoft .NET Framework

Topic Objective
To provide an overview of
the .NET Framework topics.
! The .NET Framework
Lead-in
In this section, you will learn ! Common Language Runtime
about the Microsoft .NET
Framework. ! The .NET Framework Class Library
! ADO.NET: Data and XML
! What is an XML Web Service?
! Web Forms and Services

*ILLEGAL FOR NON-TRAINER USE**

In this section, you will learn about the .NET Framework. The .NET
Framework is a set of technologies that form an integral part of the Microsoft
.NET platform. It provides the basic building blocks for developing Web
applications and XML Web services.
This section includes the following topics:
! The .NET Framework
! Common Language Runtime
! The .NET Framework Class Library
! ADO.NET: Data and XML
! What is an XML Web Service?
! Web Forms and Services
Module 1: Overview of the Microsoft .NET Framework 3

The .NET Framework

Topic Objective
To understand the
architecture of the .NET VB C++ C# Perl Python …
Framework.
Web Services User Interface
Lead-in ASP.NET
The .NET Framework is an
architecture consisting of a ADO.NET: Data and XML
runtime, the class library,
and language support. .NET Framework Class Library

Common Language Runtime

COM+
Message
(Transactions, Partitions, IIS WMI
Queuing
Object Pooling)

Win32

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework

The .NET Framework provides the necessary compile time and runtime
foundation to build and run .NET applications. The .NET Framework is the
primary focus of this course.

Platform Substrate
The .NET Framework must run on an operating system. Currently, the .NET
Framework is built to work on the Microsoft Win32® operating systems. In the
future, the .NET Framework will be extended to run on other platforms, such as
Microsoft Windows® CE.

Application Services
When running on Microsoft Windows 2000, application services, such as
COM+, Message Queuing, Windows Internet Information Server (IIS), and
Windows Management Instrumentation (WMI), are available to the developer.
The .NET Framework exposes application services through classes in the .NET
Framework class library.

Common Language Runtime

The common language runtime simplifies application development, provides a
robust and secure execution environment, supports multiple languages, and
simplifies application deployment and management.
The common language runtime environment is also referred to as a managed
environment, in which common services, such as garbage collection and
security, are automatically provided.
4 Module 1: Overview of the Microsoft .NET Framework

The .NET Framework Class Library

The .NET Framework class library exposes features of the runtime and provides
other high-level services that every developer needs. The classes simplify
development of .NET applications. Developers can extend them by creating
their own libraries of classes.

ADO.NET
ADO.NET is the next generation of Microsoft ActiveX® Data Object (ADO)
technology. ADO.NET provides improved support for the disconnected
programming model. It also provides rich XML support.

ASP.NET
Microsoft ASP.NET is a programming framework that is built on the common
language runtime. ASP.NET can be used on a server to build powerful Web
applications. ASP.NET Web Forms provide an easy and powerful way to build
dynamic Web user interfaces (UI).

XML Web Services

The .NET Framework provides tools and classes for building, testing, and
distributing XML Web services.

User Interfaces
The .NET Framework supports three types of user interfaces:
! Web Forms, which work through ASP.NET
! Windows Forms, which run on Win32 clients
! Console applications, which for simplicity, are used for most of the labs in
this course
Module 1: Overview of the Microsoft .NET Framework 5

Languages
Any language that conforms to the Common Language Specification (CLS) can
run on the common language runtime. In the .NET Framework, Microsoft
provides Microsoft Visual Basic®, Microsoft Visual C++®, Microsoft
Visual C#™, and Microsoft JScript® support. Third parties can provide
additional languages.

Note C# has been submitted for standardization to ECMA, a vendor-neutral

international standards organization committed to driving industry-wide
adoption of information and communications technologies. This standardization
will make it possible for any company which wishes to implement C#
programming tools on any platform to do so. Microsoft has also submitted a
subset of the Microsoft .NET Framework, called the Common Language
Infrastructure (CLI), to ECMA. This will make it possible for other vendors to
implement the CLI on a variety of platforms, so that software written using the
basic architectural model presented by the .NET Framework can be created
using a variety of tools on a variety of platforms.

Building Components in the .NET Framework

In the .NET Framework, components are built on a common foundation. You
no longer need to write the code to allow objects to interact directly with each
other. In addition, you no longer need to write component wrappers in the .NET
environment, because components do not use wrappers. The .NET Framework
can interpret the constructs that developers are accustomed to using in object-
oriented languages. The .NET Framework fully supports class, inheritance,
methods, properties, events, polymorphism, constructors, and other object-
oriented constructs.
6 Module 1: Overview of the Microsoft .NET Framework

Common Language Runtime

Topic Objective
To highlight some of the key .NET Framework Class Library Support
components in the common
language runtime. Thread Support COM Marshaler
Lead-in
This topic will give you an Type Checker Exception Manager
overview of the components
of the common language
runtime. I will briefly Security Engine Debugger
describe each component.
As a C# developer, you will
MSIL to Native Code Garbage
never see these discrete
pieces, but this discussion Compilers Manager Collection
will give you a better
understanding of the
richness of the runtime. Class Loader

*ILLEGAL FOR NON-TRAINER USE**

The common language runtime simplifies application development, provides a
robust and secure execution environment, supports multiple languages, and
simplifies application deployment and management.
The common language runtime environment is also referred to as a managed
environment, one in which common services, such as garbage collection and
security, are automatically provided. The common language runtime features
are described in the following table.
Component Description

Class loader Manages metadata, and the loading and layout of classes.
Microsoft Intermediate Language Converts MSIL to native code on a just-in-time basis.
(MSIL) to native compiler
Code manager Manages code execution.
Garbage collection Provides automatic lifetime management of all of objects in the .NET
Framework, garbage collection is a multiprocessor, scalable garbage collector.
Security engine Provides evidence-based security, based on user identity and the origin of the
code.
Debugger Enables the developer to debug an application and trace the execution of code.
Type checker Does not allow unsafe casts or uninitialized variables. MSIL can be verified to
guarantee type safety.
Exception manager Provides structured exception handling, which is integrated with Windows
Structured Exception Handling (SEH). Error reporting has been improved.
Thread support Provides classes and interfaces that enable multithreaded programming.
COM marshaler Provides marshaling to and from COM.
.NET Framework class library Integrates code with the runtime that supports the .NET Framework class library.
support
Module 1: Overview of the Microsoft .NET Framework 7

The .NET Framework Class Library

Topic Objective
To provide an overview of
the .NET Framework class ! Spans All Programming Languages
library and the most # Enables cross-language inheritance and debugging
common namespace: # Integrates well with tools
System.
! Is Object-Oriented and Consistent
Lead-in
# Enhances developer productivity by reducing the number of APIs to
In this topic, you will learn learn
how .NET Framework class
! Has a Built-In Common Type System
library exposes features of
the runtime and provides ! Is Extensible
other high-level services. # Makes it easy to add or modify framework features
! Is Secure
# Allows creation of secure applications

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework class library exposes features of the runtime and provides
other high-level services that every developer needs.
Because there are hundreds of classes in the .NET Framework class library,
classes are grouped into namespaces. The first part of the full name, which is
located before the rightmost dot, is the namespace name. The last part of the
name, which is located after the dot, is the type name.
For example, System.Collections.ArrayList represents the ArrayList class,
which belongs to the System.Collections namespace. The types in
System.Collections namespace can be used to manipulate collections of
objects.

Spans All Programming Languages

The .NET Framework class library is language-independent so it enables cross-
language inheritance and debugging. The .NET Framework class library also
integrates fully with Microsoft Visual Studio® .NET, making it easy to develop
applications with the library.

Is Object-Oriented and Consistent

Unlike flat APIs that are numerous and unorganized, the .NET Framework class
library is organized into namespaces and classes. This object-oriented approach
groups related functionality and data together and enables the developer to work
with the library in a more natural way.
8 Module 1: Overview of the Microsoft .NET Framework

Has a Built-In Common Type System

The .NET Framework class library is type-safe. Type safety is ensured through
the common type system, which is part of the common language runtime.

Is Extensible
You can extend the library by creating your own classes and compiling them
into libraries. If designed properly, your class library will also be object-
oriented and language-independent.

Is Secure
The .NET Framework class library provides rich security for your applications.
You can use code access security and role-based security, and configure your
own security policies. Furthermore, there are numerous security tools to assist
in certificate creation, permission viewing, and so on.
Module 1: Overview of the Microsoft .NET Framework 9

ADO.NET: Data and XML

Topic Objective
To explain the data and
XML support in the runtime.
Lead-in
ADO.NET: Data and XML
The .NET Framework
provides a new set of
ADO.NET classes to handle System.Data System.Xml
data.
OleDb SqlClient XSL
Serialization
Common SQLTypes XPath

*ILLEGAL FOR NON-TRAINER USE**

ADO.NET, the next generation of ADO technology provides improved support
for disconnected programming. It also provides rich XML support in the
System.Xml namespace.

System.Data Namespace
The System.Data namespace consists of classes that constitute the ADO.NET
object model. At a high level, the ADO.NET object model is divided into two
layers: the connected layer and the disconnected layer.
The System.Data namespace includes the DataSet class, which represents
multiple tables and their relations. These data sets are completely self-contained
data structures that can be populated from a variety of data sources. One data
source could be XML; another data source could be an OLE DB; and a third
data source could be the direct adapter for Microsoft SQL Server™.

System.Xml Namespace
The System.Xml namespace provides support for XML. It includes an XML
parser and a writer, which are W3C-compliant. The Extensible Stylesheet
Language for Transformation (XSLT) is provided by the System.Xml.Xsl
namespace. The implementation of XPath, a comprehensive language for
document addressing, enables data graph navigation in XML. The
System.Xml.Serialization namespace provides the entire core infrastructure
for XML Web services, including such features as moving back and forth from
objects to an XML representation.
10 Module 1: Overview of the Microsoft .NET Framework

What Is an XML Web Service?

Topic Objective XML Web
To define an XML Web Open service
service.
Internet
Lead-in Protocols A programmable application component
XML Web services are the accessible via standard Web protocols
fundamental building blocks
UDDI
of the .NET platform. ! Provide a Directory of Services on the Internet Universal Description,
Discovery, and Integration

! XML Web services are defined in terms of the WSDL

formats and ordering of messages Web Services
Description Language

! XML Web services consumers can send and

SOAP
receive messages using XML

! Built using open Internet protocols XML & HTTP

*ILLEGAL FOR NON-TRAINER USE**

XML Web services are an integral part of the .NET platform. They are the
fundamental mechanism for exposing and consuming data and functionality
across Web applications, both inside organizations and across organizations.
XML Web services are units of application logic that provide data and services
to other applications. Applications access XML Web services by means of
industry standard Web protocols and data formats, such as HTTP, XML, and
Simple Object Access Protocol (SOAP), regardless of how each XML Web
service is implemented.

XML and HTTP

XML Web services are built by using XML and HTTP. Because they are built
with XML and HTTP, XML Web services operate without firewall restrictions.
Also, because XML and HTTP are industry standards, any platform supporting
XML and HTTP can work with XML Web services.

SOAP
SOAP defines how messages are formatted, sent, and received when working
with XML Web services. SOAP is also an industry standard that is built on
XML and HTTP. Any platform that supports the SOAP standard can support
XML Web services.
Module 1: Overview of the Microsoft .NET Framework 11

Web Services Description Language

The Web Services Description Language (WSDL) is an XML format for
describing the network services that are offered by the server. You use WSDL
to create a file that identifies the services that are provided by the server and the
set of operations within each service that the server supports. For each of the
operations, the WSDL file also describes the format that the client must follow
when requesting an operation.

Universal Description, Discovery, and Integration

Universal Description, Discovery, and Integration (UDDI) is an industry
standard for registering and searching for XML Web services. By using UDDI,
developers can discover and use XML Web services that are available publicly
over the Internet.
For more information on UDDI, see Web Service Discovery in Module 13,
“Remoting and XML Web Services,” in Course 2349B, Programming with the
Microsoft.NET Framework (Microsoft Visual C# .NET), and the UDDI Web
site at http://www.uddi.org.
12 Module 1: Overview of the Microsoft .NET Framework

Web Forms and Services

Topic Objective
To show where Web Forms
and XML Web services are
found in the ASP.NET
ASP.NET
programming model. System.Web
Lead-in Services UI
The Internet is quickly Description HtmlControls
evolving from today’s Web
sites that simply deliver UI Discovery WebControls
pages to browsers to a next Protocols
generation of programmable
Web sites that link Caching Security
organizations, applications, Configuration SessionState
services, and devices
directly.

*ILLEGAL FOR NON-TRAINER USE**

ASP.NET is a programming framework built on the common language runtime
that can be used on a server to build powerful Web applications. ASP.NET
Web Forms provide an easy and powerful way to build dynamic Web UI pages.
ASP.NET XML Web services provide the building blocks for constructing
distributed Web-based applications. XML Web services are based on open
Internet standards, such as HTTP and XML.
The common language runtime provides built-in support for creating and
exposing XML Web services by using a programming abstraction that is
consistent and familiar to both ASP Web Forms and Visual Basic developers.
The resulting model is both scalable and extensible. This model is based on
open Internet standards, such as HTTP, XML, SOAP, and WSDL, so it can be
accessed and interpreted by any client or Internet-enabled device. Some of the
more common ASP.NET classes are described in this topic as follows:

System.Web
In the System.Web namespace, there are lower-level services, such as caching,
security, and configuration, which are shared between XML Web services and
Web UIs.

System.Web.Services
The System.Web.Services namespace has classes that handle XML Web
services, such as protocols and discovery.

Controls
There are two types of controls: HTML controls and Web controls. The
System.Web.UI.HtmlControls namespace gives you direct mapping of HTML
tags, such as input. The System.Web.UI.WebControls namespace enables you
to structure controls with templates, such as grid controls.
Module 1: Overview of the Microsoft .NET Framework 13

" Overview of Namespaces

Topic Objective
To provide an overview of
the namespaces in the .NET
Framework. ! Namespaces
Lead-in ! Namespaces Used in this Course
In this section, you will learn
about the namespaces in ! Namespaces Covered in Optional Modules
the .NET Framework.

*ILLEGAL FOR NON-TRAINER USE**

In this section, you will learn about the namespaces in the Microsoft .NET
Framework. You will also learn about which namespaces are taught in this
course.
This section includes the following topics:
! Namespaces
! Namespaces Used in this Course
! Namespaces Covered in Optional Modules
14 Module 1: Overview of the Microsoft .NET Framework

Namespaces
Topic Objective
To understand how
namespaces provide an
easy-to-use hierarchy of
types and functionality.
Lead-in System
The .NET Framework Collections IO Security Runtime
includes a large set of class
Configuration Net ServiceProcess
library assemblies, which
contain hundreds of types. Diagnostics Reflection Text
These assemblies provide Globalization Resources Threading
access to system
functionality in your
development process.

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework includes a large set of class library assemblies, which
contain hundreds of types. These assemblies provide access to system
functionality in your development process.

The Purpose of Namespaces

Because the .NET Framework class library includes definitions for so many
types, the library is organized in a hierarchical namespace structure.
Namespaces use a dot-syntax naming scheme to group logically related classes
together so that they can be easily searched and referenced. For example, the
System.Data namespace contains the classes that constitute the ADO.NET
architecture. The System.Xml namespace is the overall namespace for the
XML classes that provide standards-based support for processing XML.

The System Namespace

The System namespace is the root namespace for types in the .NET
Framework. The System namespace contains the base type Object, from which
all other types are derived.
The System namespace also contains types for exception handling, garbage
collection, console I/O, various tool types, format data types, random number
generators, and math functions.
Module 1: Overview of the Microsoft .NET Framework 15

Namespaces Used in this Course

Topic Objective
To explain which Module 2 Module 10
namespaces are taught in System.IO
this course, and which # System.Console #

namespaces are not taught. Module 3 Module 11

Lead-in # System.Net
# System.Windows.Forms
This course covers many of # System.Net.Sockets
the System namespaces. # System.Drawing
Not all namespaces are Module 12
Module 4
covered, for example the # System.Runtime.Serialization
System.Security # System.Reflection
Module 13
namespaces. Module 7
# System.Runtime.Remoting.Channels
# System.Text
# System.Web.Services
# System.Collections

*ILLEGAL FOR NON-TRAINER USE**

This course covers many of the namespaces in the Microsoft .NET Framework.
Module 2 teaches the System.Console namespace for printing output to the
console. Module 3 teaches the System.Windows.Forms and System.Drawing
namespaces for building a form with buttons that interacts with the user.
Module 4 teaches the System.Reflection namespace for storing version and key
file information in an assembly. Module 7 teaches the System.Text namespace
for advanced string management, and System.Collections for maintaining
collections of data.
Module 10 teaches the System.IO namespace for reading and writing to files.
Module 11 teaches the System.Net and System.Net.Sockets namespaces for
transmitting data over the network.
Module 12 teaches the System.Runtime.Serialization namespace for
persisting objects to storage. Module 13 teaches the
System.Runtime.Remoting.Channels and System.Web.Services namespaces
for invoking remote objects, and building XML Web services.
16 Module 1: Overview of the Microsoft .NET Framework

Namespaces Covered in Optional Modules

Topic Objective
To complete the namespace
information that was
presented in the preceding Module 14
slide.
# System.Threading
Lead-in
Here are some more Module 16
namespaces that are
covered in optional Modules # System.Data
14 through 17 of this course.
Module 17
# System.Reflection

*ILLEGAL FOR NON-TRAINER USE**

Modules 14 through 17 are optional modules.
Module 14 teaches the System.Threading namespace for enabling
multithreaded programming. Module 16 teaches the System.Data namespace,
which provides the base objects and types for the ADO.NET programming
model. ADO.NET also provides rich XML support in the System.Xml
namespace. Finally, Module 17 teaches the System.Reflection namespace,
which contains classes that you can use for examining metadata.

Namespaces Not Covered

This course does not teach the System.Security namespace. For more
information about System.Security and related security namespaces, see
Course 2350A, Securing and Deploying Microsoft .NET Assemblies.
Module 1: Overview of the Microsoft .NET Framework 17

Review
Topic Objective
To reinforce module
objectives by reviewing
key points. ! Overview of the Microsoft .NET Framework
Lead-in ! Overview of Namespaces
The review questions cover
some of the key concepts
taught in the module.

*ILLEGAL FOR NON-TRAINER USE**

1. List the components of the .NET Framework.
The common language runtime, .NET Framework class library, data
and XML, XML Web services and Web Forms, and Windows Forms.

2. What is the purpose of the common language runtime?

It provides an environment in which you can execute code.

3. What is the purpose of the common language specification?

It defines a set of features that all .NET languages should support.

4. What is an XML Web service?

An XML Web service is a programmable Web component that can be
shared among applications on the Internet or an intranet.

5. What is a managed environment?

A managed environment is an environment that provides services, such
as garbage collection, security, and other related features.
THIS PAGE INTENTIONALLY LEFT BLANK
Module 2: Introduction
to a Managed Execution
Environment
Contents

Overview 1
Writing a .NET Application 2
Compiling and Running a .NET Application 11
Lab 2: Building a Simple .NET Application 29
Review 32
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, place or event is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

 2001-2002 Microsoft Corporation. All rights reserved.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Module 2: Introduction to a Managed Execution Environment iii

Instructor Notes
Presentation: After completing this module, students will be able to:
45 Minutes
! Create simple console applications in C#.
Lab: ! Explain how code is compiled and executed in a managed execution
20 Minutes
environment.
! Explain the concept of garbage collection.

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach
this module.

Required Materials
To teach this module, you need the following materials:
! Microsoft® PowerPoint® file 2349B_02.ppt
! Sample managed module HelloDemoCS.exe

Preparation Tasks
To prepare for this module, you should:
! Read all of the materials for this module.
! Practice the demonstrations.
! Review the animation.
! Complete the lab.
iv Module 2: Introduction to a Managed Execution Environment

Demonstrations
This section provides demonstration procedures that will not fit in the margin
notes or are not appropriate for the student notes.

Hello World
This demonstration shows how to build a simple application in C#.
In the following procedures, use Notepad to create the simple Hello World
application, and build and run the HelloDemoCS.exe application from the
command line.

! To create the source code in C#

1. Open Notepad and type the following code:
// Allow easy reference to System namespace classes
using System;

// Create class to hold program entry point

class MainApp {
public static void Main() {

// Write text to the console

Console.WriteLine(“Hello World using C#!”);
}
}

2. Save the file as HelloDemoCS.cs.

Important To use Microsoft Visual Studio® .NET tools within a command

prompt window, the command prompt window must have the proper
environment settings. The Visual Studio .NET Command Prompt window
provides such an environment. To run a Visual Studio .NET Command Prompt
window, click Start, All Programs, Microsoft Visual Studio .NET,
Visual Studio .NET Tools, and Visual Studio .NET Command Prompt.
Module 2: Introduction to a Managed Execution Environment v

! To compile the source code and build an executable program

• From a Visual Studio .NET Command Prompt window, type the following
syntax:
csc HelloDemoCS.cs

Running the resulting executable file will generate the following output:
Hello World using C#!

Viewing Assembly Metadata by Using the MSIL

Disassembler
This demonstration shows how to use the Microsoft Intermediate Language
(MSIL) Disassembler (Ildasm.exe) to view an assembly’s metadata.
The code for this demonstration is contained in one project and is located in
<install folder>\Democode\Mod02. To demonstrate how to use the MSIL
Disassembler to view the contents of the HelloDemoCS.exe assembly, follow
the directions in Demonstration: Using the MSIL Disassembler in this module.
vi Module 2: Introduction to a Managed Execution Environment

Multimedia
This section lists the multimedia items that are part of this module. Instructions
for launching and playing the multimedia are included with the relevant slides.

Application Loading and Single-File Assembly Execution

This animation will show students how a single-file private assembly is loaded
and executed.

Module Strategy
Use the following strategy to present this module:
! Writing a .NET Application
Stress the importance of understanding the process of compiling and
running Microsoft .NET Framework applications, by using the simple Hello
World application. Focus primarily on the compilation and execution
processes.
! Compiling and Running a .NET Application
This section introduces basic concepts of a managed execution environment
and presents new terminology. Many of these concepts are covered in
greater detail in subsequent modules in this course, in subsequent courses,
and in the .NET Framework software development kit (SDK)
documentation.
Emphasize that you are primarily introducing new concepts and
terminology. Be prepared to postpone answering questions that pertain to
information that is covered in later modules. Encourage students to start
reading the .NET Framework SDK documentation.
Module 2: Introduction to a Managed Execution Environment 1

Overview
Topic Objective
To provide an overview of
the module topics and
objectives. ! Writing a .NET Application
Lead-in ! Compiling and Running a .NET Application
This module introduces the
concept of managed
execution and shows you
how to quickly build
applications that use the
Microsoft .NET Framework
common language runtime
environment.

*ILLEGAL FOR NON-TRAINER USE**

This module introduces the concept of managed execution and shows you how
to quickly build applications that use the Microsoft® .NET Framework common
language runtime environment. A simple Hello World version of a console
application illustrates most of the concepts that are introduced in this module.
Because this course is an introduction to programming in the .NET Framework,
you should spend some time reading the .NET Framework software
development kit (SDK) documentation. In fact, the labs, demonstrations, and
material for this module and other modules in this course are based on several
tutorials in the .NET Framework SDK.
After completing this module, you will be able to:
! Create simple console applications in C#.
! Explain how code is compiled and executed in a managed execution
environment.
! Explain the concept of garbage collection.
2 Module 2: Introduction to a Managed Execution Environment

" Writing a .NET Application

Topic Objective
To introduce the topics in
the section.
! Using a Namespace
Lead-in
Because all supported ! Defining a Namespace and a Class
languages use the Common
Type System and the .NET ! Entry Points, Scope, and Declarations
Framework class library,
and run in the common ! Console Input and Output
language runtime, programs
! Case Sensitivity
in the supported languages
are similar.

*ILLEGAL FOR NON-TRAINER USE**

Because all supported languages use the Common Type System and the .NET
Framework base class library, and run in the common language runtime,
programs in the supported languages are similar. The most significant
difference in programming with the supported languages is syntax.

Delivery Tip Note In this module, and in Modules 3 and 4, Notepad is used as the source
Stress the importance of code editor, instead of the Microsoft Visual Studio® .NET development
understanding the process environment. The examples in these modules are simple enough to be compiled
of compiling and running the and built directly from a command prompt window. Working in Notepad will
.NET applications. Using allow you to focus on the compilation and execution processes.
Visual Studio .NET at this
time may obscure the
underlying processes.
Module 2: Introduction to a Managed Execution Environment 3

Demonstration: Hello World

Topic Objective
To demonstrate how to build
a simple application in C#.
Lead-in
In this demonstration, you
will learn how to build a
simple application in C#.

*ILLEGAL FOR NON-TRAINER USE**

In this demonstration, you will learn how to build a simple application in C#.

Delivery Tip ! To create the source code in C#

As this is a short, simple 1. Open Notepad and type the following code:
demonstration, you may
want to let students try it // Allow easy reference to System namespace classes
themselves. using System;

// Create class to hold program entry point

class MainApp {
public static void Main() {

// Write text to the console

Console.WriteLine(“Hello World using C#!”);
}
}

2. Save the file as HelloDemoCS.cs

4 Module 2: Introduction to a Managed Execution Environment

! To compile the source code and build an executable program

Important To use Visual Studio .NET tools within a command prompt
window, the command prompt window must have the proper environment
settings. The Visual Studio .NET Command Prompt window provides such an
environment. To run a Visual Studio .NET Command Prompt window, click
Start, All Programs, Microsoft Visual Studio .NET, Visual Studio .NET
Tools, and Visual Studio .NET Command Prompt.

• From a Visual Studio .NET Command Prompt window, type the following
syntax:
csc HelloDemoCS.cs

Running the resulting executable will generate the following output:

Hello World using C#!
Module 2: Introduction to a Managed Execution Environment 5

Using a Namespace
Topic Objective
To describe how to use
namespaces in the .NET ! Classes Can Be Fully Referenced
Framework.
Lead-in //
// declares
declares aa FileStream
FileStream object
object
You can fully reference System.IO.FileStream
System.IO.FileStream aFileStream;
aFileStream;
classes in which an instance
of System.IO.FileStream is ! Or the Namespace of a Class Can Be Referenced
declared by using C#:
# No need to fully qualify contained class names

using
using System.IO;
System.IO;
...
...
FileStream
FileStream aFileStream;
aFileStream;

*ILLEGAL FOR NON-TRAINER USE**

You can fully reference classes, as in the following example, in which an
instance of System.IO.FileStream is declared by using C#:
System.IO.Filestream aFileStream;

However, it is more convenient to reference the required namespaces in your

program. Using the namespace effectively disposes of the need to qualify all
class library references, as in the following example:
using System.IO;
...
FileStream aFileStream;

For example, in order to have convenient access to System objects, you must
use the System namespace.
6 Module 2: Introduction to a Managed Execution Environment

Defining a Namespace and a Class

Topic Objective
To describe how to define
namespaces and classes in
C#. ! C# Supports Creation of Custom Namespaces and
Classes Within Those Namespaces
Lead-in
C# supports the creation of
custom namespaces and namespace
classes within those namespace CompCS
CompCS {{
public
public class
class StringComponent
StringComponent {{
namespaces.
...
...
}}
}}

*ILLEGAL FOR NON-TRAINER USE**

C# supports the creation of custom namespaces and classes within those
namespaces.

Tip The following is the general rule for naming namespaces:

CompanyName.TechnologyName
For example:
Microsoft.Office
This is merely a guideline. Third-party companies can choose other names.

Namespaces in C#
In C#, you use the namespace statement to define a new namespace, which
encapsulates the classes that you create, as in the following example:
namespace CompCS {
public class StringComponent {
...
}
}

Note that a namespace may be nested in other namespaces, and a single

namespace may be defined in multiple files. A single source code file may also
define multiple namespaces.
Module 2: Introduction to a Managed Execution Environment 7

Entry Points, Scope, and Declarations

Topic Objective
To describe how to create ! In C#, the External Entry Point for a Program Is in a Class
program entry points in C#.
class
class MainApp
MainApp
Lead-in {{ public
public static
static voidvoid Main()
Main()
Every executable program {. .
{. . .}.}
must contain an external }}
entry point, where the
application begins its ! C# Supports the Use of a Period As a Scope Resolution Operator
execution.
Console.WriteLine
Console.WriteLine ("First
("First String");
String");

! In C#, Objects Must Be Declared Before They Can Be Used and Are
Instantiated Using the New Keyword

Lib.Comp
Lib.Comp myComp
myComp == new
new Lib.Comp();
Lib.Comp();

*ILLEGAL FOR NON-TRAINER USE**

Every executable program must contain an external entry point, where the
application begins its execution. In C#, all code must be contained in methods
of a class.

Entry Points in C#
To accommodate the entry point code in C#, you must first specify the class, as
in the following example:
class MainApp {...}

Next, you specify the entry point for your program. The compiler requires this
entry point to be a public static method called Main, as in the following
example:
public static void Main () {...}

Scope
C# uses the period as a scope resolution operator. For example, you use the
syntax Console.WriteLine when referencing the WriteLine method of the
Console object.

Declaring and Instantiating Variables

In C#, you must declare a variable before it can be used. To instantiate the
object, use the new keyword. The following example in C# shows how to
declare an object of type Comp, in namespace Lib, with the name myComp:
Lib.Comp myComp = new Lib.Comp();
8 Module 2: Introduction to a Managed Execution Environment

Console Input and Output

Topic Objective
To describe how to use
Console class methods
in C#. ! Console Class Methods
Lead-in # Read, ReadLine, Write, and WriteLine
You can use the runtime
Console class of the
System namespace for
input and output to the Console.WriteLine("Hello
Console.WriteLine("Hello World
World using
using C#!");
C#!");
console of any string or
numeric value by using the
Read, ReadLine, Write,
and WriteLine methods.

*ILLEGAL FOR NON-TRAINER USE**

You can use the common language runtime Console class of the System
namespace for input and output to the console of any string or numeric value by
using the Read, ReadLine, Write, and WriteLine methods.
The following example shows a C# program that outputs a string to the console:
using System;

class MainApp {
public static void Main() {

// Write text to the console

Console.WriteLine(“Hello World using C#!”);
}
}
Module 2: Introduction to a Managed Execution Environment 9

Case Sensitivity
Topic Objective
To describe case sensitivity ! Do Not Use Names That Require Case Sensitivity
issues in programming
languages. # Components should be fully usable from both case-
Lead-in sensitive and case-insensitive languages
C++ and C# are case-
sensitive, but Visual Basic is
# Case should not be used to distinguish between
not case-sensitive. identifiers within a single name scope
! Avoid the Following
class
class customer
customer {...}
{...}
class
class Customer
Customer {...}
{...}

void
void foo(int
foo(int X,
X, int
int x)
x)

*ILLEGAL FOR NON-TRAINER USE**

Microsoft Visual C++® and C# are case-sensitive, but Microsoft Visual Basic®
is not case-sensitive. To ensure that a program is compliant with the Common
Language Specification (CLS), however, you must take special care with public
names. You cannot use case to distinguish between identifiers within a single
name scope, such as types within assemblies and members within types.
The following examples show situations to avoid:
! Do not have two classes or namespaces whose names differ only by case.
class customer { ... }
class Customer { ... }

! Do not have a function with two parameters whose names differ only by
case.
void foo(int X, int x)

This constraint enables Visual Basic (and potentially other case-insensitive

languages) to produce and use components that have been created in other case-
sensitive languages. This constraint does not apply to your definitions of private
classes, private methods on public classes, or local variables.
10 Module 2: Introduction to a Managed Execution Environment

Note To fully interact with other objects regardless of the language they were
implemented in, objects must expose to callers only those features that are
common to all the languages they must interoperate with. For this reason, a set
of language features has been defined, called the Common Language
Specification (CLS), which includes common language features that are needed
by many applications. The CLS rules define a subset of the common type
system; that is, all the rules that apply to the common type system apply to the
CLS, except where stricter rules are defined in the CLS. If your component uses
only CLS features in the API that it exposes to other code (including derived
classes), the component is guaranteed to be accessible from any programming
language that supports the CLS. Components that adhere to the CLS rules and
use only the features included in the CLS are said to be CLS-compliant
components.
Module 2: Introduction to a Managed Execution Environment 11

" Compiling and Running a .NET Application

Topic Objective
To introduce the topics in ! Compiler Options
the section.
! The Process of Managed Execution
Lead-in
Most aspects of ! Metadata
programming in the .NET
Framework are the same for ! Microsoft Intermediate Language
all compatible languages;
each supported language ! Assemblies
compiler produces self- ! Common Language Runtime Tools
describing, managed
Microsoft intermediate ! Just-In-Time Compilation
language (MSIL) code.
! Application Domains
! Garbage Collection

*ILLEGAL FOR NON-TRAINER USE**

Most aspects of programming in the .NET Framework are the same for all
compatible languages; each supported language compiler produces self-
describing, managed Microsoft intermediate language (MSIL) code. All
managed code runs using the common language runtime, which provides
Delivery Tip cross-language integration, automatic memory management, cross-language
Emphasize that you are
exception handling, enhanced security, and a consistent and simplified
primarily introducing new
concepts and terminology.
programming model.
Be prepared to postpone This section introduces basic concepts of a managed execution environment and
answering questions that
presents new terminology. Many of these concepts are covered in greater detail
pertain to later modules.
Encourage students to start
in subsequent modules in this course, in subsequent courses, and in the .NET
reading the .NET Framework SDK documentation.
Framework SDK
documentation.

Key Points
String literals in an
application are stored and
transported as clear text.
Therefore, you should avoid
putting sensitive information
such as passwords in string
literals.
12 Module 2: Introduction to a Managed Execution Environment

Compiler Options
Topic Objective
To introduce compiler
options in C#. ! Compile Directly from a Command Prompt Window
Lead-in >csc
>csc HelloDemoCS.cs
HelloDemoCS.cs
The .NET Framework
includes a command line
compiler for C#. ! Use /t to indicate target

>csc
>csc /t:exe
/t:exe HelloDemoCS.cs
HelloDemoCS.cs

! Use /reference to reference assemblies

>csc
>csc /t:exe
/t:exe /reference:assemb1.dll
/reference:assemb1.dll HelloDemoCS.cs
HelloDemoCS.cs

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework includes a command line compiler for C#. The file name
of the compiler is Csc.exe.

Compiling in C#
To compile the source code for the Hello World application presented in the
Hello World demonstration at the beginning of this module, type the following:
csc HelloDemoCS.cs

This syntax invokes the C# compiler. In this example, you only need to specify
the name of the file to be compiled. The compiler generates the program
executable, HelloDemoCS.exe.
Module 2: Introduction to a Managed Execution Environment 13

Command Line Options

In C#, you can obtain the complete list of command line options by using the
/? switch as follows:

csc /?

Common options include the /out switch, which specifies the name of the
output file, and the /target switch, which specifies the target type. By default,
the name of the output file is the name of the input file with an .exe extension.
The default for the target type is an executable program.
The following example shows the use of both the /out and /t switches in C#:
csc /out:HelloDemoCS.exe /t:exe HelloDemoCS.cs

The /t switch is equivalent to the /target switch.

For more information about compiler options, see the .NET Framework SDK
documentation.

Using the /reference Compilation Option

When referring to other assemblies, you must use the /reference compilation
switch. The /reference compilation option allows the compiler to make
information in the specified libraries available to the source that is currently
being compiled.
The following example shows how to build an executable program from the
command line by using the /reference compilation option.
csc /r:assemb1.dll,assemb2.dll /out:output.exe input.cs

The /r switch is equivalent to the /reference compilation switch.

14 Module 2: Introduction to a Managed Execution Environment

The Process of Managed Execution

Topic Objective
EXE/DLL
To introduce fundamental EXE/DLL
(MSIL Compiler
Compiler Source
Source
(MSILand
and
concepts of compiling and metadata)
metadata)
Code
Code
executing code in a
managed execution Class
Class
Class
Class Loader
Loader
environment. Libraries
Libraries
(MSIL
(MSILand
and JIT
JIT Compiler
Compiler
Lead-in metadata)
metadata) with
with optional
optional
verification
verification
In the .NET Framework, the
common language runtime
Trusted, Call to an
provides the infrastructure pre-JITed
Managed
uncompiled
Native
for a managed execution code only Code method
environment.
Execution
Execution

Security
Security Checks
Checks
Runtime Engine

*ILLEGAL FOR NON-TRAINER USE**

In the .NET Framework, the common language runtime provides the
infrastructure for a managed execution environment. This topic introduces
fundamental concepts of compiling and executing code in a managed execution
environment and identifies new terminology.

Compiling Source Code

When you develop an application in the .NET Framework, you can write the
source code in any programming language as long as the compiler that you use
to compile the code targets the common language runtime. Compilation of the
source code produces a managed module. The managed module is contained
within a physical file also known as a portable executable (PE) file.
The file may contain the following items:
! Microsoft Intermediate Language (MSIL)
The compiler translates the source code into MSIL, a CPU-independent set
of instructions that can be efficiently converted to native code.
! Type Metadata
This information fully describes types, members, and other references, and
is used by the common language runtime at run time.
! A Set of Resources
For example, .bmp or .jpg files.
Module 2: Introduction to a Managed Execution Environment 15

If the C# compiler’s target option is either exe or library, then the compiler
produces a managed module that is an assembly. Assemblies are a fundamental
part of programming with the .NET Framework. Assemblies are the
fundamental units of sharing, deployment, security, and versioning in the
common language runtime. The .NET common language runtime only executes
MSIL code that is contained in an assembly.
If the C# compiler’s target option is module, then the compiler produces a
managed module that is not an assembly, it does not contain a manifest and
cannot be executed by the common language runtime. A managed module can
be added to an assembly by the C# compiler, or by using the .NET’s Assembly
Generation Tool, Al.exe.
Subsequent topics in this module cover MSIL, metadata, and assemblies in
more detail.

Executing Code
When a user executes a managed application, the operating system loader loads
the common language runtime, which then begins executing the module’s
managed MSIL code. Because current host CPUs cannot execute the MSIL
instructions directly, the common language runtime must first convert the MSIL
instructions into native code.
The common language runtime does not convert all of the module’s MSIL code
into CPU instructions at load time. Instead, it converts the instructions when
functions are called. The MSIL is compiled only when needed. The component
of the common language runtime that performs this function is called the just-
in-time (JIT) compiler. JIT compilation conserves memory and saves time
during application initialization.
For more information about the JIT compiler, see Just-In-Time Compilation in
this module.

Application Domain
Operating systems and runtime environments typically provide some form of
isolation between applications. This isolation is necessary to ensure that code
running in one application cannot adversely affect other, unrelated applications.
Application domains provide a secure and versatile unit of processing that the
common language runtime can use to provide isolation between applications.
Application domains are typically created by runtime hosts, which are
responsible for bootstrapping the common language runtime before an
application is run.
16 Module 2: Introduction to a Managed Execution Environment

Metadata
Topic Objective
To explain how metadata is
used in the common ! Declarative Information Emitted at Compile Time
language runtime.
Lead-in ! Included with All .NET Framework Files and Assemblies
Every compiler that targets
the common language ! Metadata Allows the Runtime to:
runtime is required to emit
# Load and locate code
full metadata into every
managed module. # Enforce code security
# Generate native code at runtime
# Provide reflection

*ILLEGAL FOR NON-TRAINER USE**

Every compiler that targets the common language runtime is required to emit
full metadata into every managed module. This topic explains how the common
language runtime uses metadata.

Definition of Metadata
Metadata is a set of data tables, which fully describe every element that is
defined in a module. This information can include data types and members with
their declarations and implementations, and references to other types and
members.
Metadata provides the common language runtime with all the information that
is required for software component interaction. It replaces older technologies,
such as Interface Definition Language (IDL) files, type libraries, and external
registration. Metadata is always embedded in the .exe or .dll file containing the
MSIL code. Therefore, it is impossible to separate metadata from the MSIL
code.
Module 2: Introduction to a Managed Execution Environment 17

Uses for Metadata

Metadata has many uses, but the following uses are most important:
! Locating and loading classes
Because metadata and MSIL are included in the same file, all type
information in that file is available to the common language runtime at
compile time. There is no need for header files because all types in a
particular assembly are described by the assembly’s manifest.
! Enforcing security
The metadata may or may not contain the permissions required for the code
to run. The security system uses permissions to prevent code from accessing
resources that it does not have authority to access.

Other uses for metadata include:

! Resolving method calls.
! Setting up runtime context boundaries.
! Providing reflection capability.

For more information about metadata, see “Metadata and Self-Describing

Components” in the .NET Framework SDK documentation.
For more information about verification of type safety, see Module 4,
“Deployment and Versioning,” in Course 2349B, Programming with the
Microsoft .NET Framework (Microsoft Visual C#™ .NET).
18 Module 2: Introduction to a Managed Execution Environment

Microsoft Intermediate Language

Topic Objective
To introduce MSIL and JIT
compilation.
! Produced by Each Supported Language Compiler
Lead-in
Microsoft intermediate ! Converted to Native Language by the Common
language, sometimes called Language Runtime's JIT Compilers
managed code, is the set of
instructions that the
compiler produces as it
compiles source code.

*ILLEGAL FOR NON-TRAINER USE**

Microsoft intermediate language (MSIL), sometimes called managed code, is
the set of instructions that the compiler produces as it compiles source code.
This topic explains MSIL and the general process for converting MSIL to
native code.

Compiled MSIL
Regardless of their logical arrangement, most assemblies contain code in the
form of MSIL. MSIL is a CPU-independent machine language created by
Microsoft in consultation with third-party compiler vendors. However, MSIL is
a much higher-level language than most CPU machine languages.
MSIL contains instructions for many common operations, including
instructions for creating and initializing objects, and for calling methods on
objects. In addition, it includes instructions for arithmetic and logical
operations, control flow, direct memory access, and exception handling.

Conversion to Native Code

Before MSIL code can be executed, it must be converted to CPU-specific or
native code by a JIT compiler. The common language runtime provides an
architecture-specific JIT compiler for each CPU architecture. These
architecture-specific JIT compilers allow you to write managed code that can be
JIT compiled and executed on any supported architecture.

Note Any managed code that calls platform-specific native APIs or libraries
can only run on a specific operating system.

For more information about MSIL, see the .NET Framework SDK
documentation.
Module 2: Introduction to a Managed Execution Environment 19

Assemblies
Topic Objective ManagedModule
Managed Module
This topic introduces the (MSILand
(MSIL andMetadata)
Metadata)
concept of an assembly and
the role of the assembly ManagedModule
Managed Module
(MSILand
(MSIL andMetadata)
Metadata) Assembly
manifest. Assembly

Lead-in
The common language
runtime uses an assembly Manifest
Manifest
.html
as the functional unit of
sharing and reuse.
.gif
Multiple Managed
Modules and
Resource Files Resource Files
Are Compiled to
Produce an Assembly

*ILLEGAL FOR NON-TRAINER USE**

The common language runtime uses an assembly as the functional unit of
sharing and reuse.

Definition of an Assembly
An assembly is a unit of class deployment, analogous to a logical .dll. Each
assembly consists of all the physical files that make up the functional unit: any
managed modules, and resource or data files.
Conceptually, assemblies provide a way to consider a group of files as a single
entity. You must use assemblies to build an application, but you can choose
how to package those assemblies for deployment.
An assembly provides the common language runtime with the information that
it needs to understand types and their implementations. As such, an assembly is
used to locate and bind to referenced types at run time.
20 Module 2: Introduction to a Managed Execution Environment

The Assembly Manifest

An assembly contains a block of data known as a manifest, which is a table in
which each entry is the name of a file that is part of the assembly. The manifest
includes the metadata that is needed to specify the version requirements,
security identity, and the information that is used to define the scope of the
assembly and resolve references to resources and classes. Because the metadata
makes an assembly self-describing, the common language runtime has the
information it requires for each assembly to execute.
All applications that are executed by the common language runtime must be
composed of an assembly or assemblies. All files that make up an assembly
must be listed in the assembly’s manifest. The manifest can be stored in single-
file assemblies or multi-file assemblies:
! Single-file assemblies
When an assembly has only one associated file, the manifest is integrated
into a single PE file.
! Multi-file assemblies
When an assembly has more than one associated file, the manifest can be a
standalone file, or it can be incorporated into one of the PE files in the
assembly.

For more information about assemblies, see “Assemblies” in the .NET

Framework SDK documentation.
Module 2: Introduction to a Managed Execution Environment 21

Common Language Runtime Tools

Topic Objective
This topic describes how the
MSIL Assembler and MSIL
Disassembler work. ! Runtime Utilities for Working with MSIL
Lead-in # MSIL Assembler (ilasm.exe) produces a final executable
The common language binary
runtime provides two tools
that you can use together to # MSIL Disassembler (ildasm.exe) inspects metadata and
test and debug MSIL code. code of a managed binary

*ILLEGAL FOR NON-TRAINER USE**

The common language runtime provides two tools that you can use to test and
debug MSIL code.
! The MSIL Assembler
The MSIL Assembler (Ilasm.exe) takes MSIL as text input and generates a
PE file, which contains the binary representation of the MSIL code and
required metadata. The basic syntax is as follows:
ilasm [options] filename [options]
! The MSIL Disassembler
You can use the MSIL Disassembler (Ildasm.exe) to examine the metadata
and disassembled code of any managed module. You will use this tool to
examine MSIL code in Lab 2, Building a Simple .NET Application.
22 Module 2: Introduction to a Managed Execution Environment

Demonstration: Using the MSIL Disassembler

Topic Objective
To demonstrate how the
MSIL Disassembler works.
Lead-in
This demonstration shows
how to use the MSIL
Disassembler to view an
assembly’s metadata.

*ILLEGAL FOR NON-TRAINER USE**

This demonstration shows how to use the MSIL Disassembler to view an
assembly’s metadata.

Viewing Assembly Metadata by Using the MSIL

Disassembler
In the following procedures, you will see how to use the MSIL Disassembler
(Ildasm.exe) to view the contents of the HelloDemoCS.exe assembly.

! To run the MSIL Disassembler on the HelloDemoCS.exe assembly

• At a Visual Studio .NET Command Prompt window, change the directory to
<install folder>\Democode\Mod02 where the sample file
HelloDemoCS.exe has been copied, and type the following command:
ildasm HelloDemoCS.exe
Module 2: Introduction to a Managed Execution Environment 23

After you expand the MainApp icon, the MSIL Disassembler graphical user
interface (GUI) displays information about the file HelloDemoCS.exe, as
shown in the following illustration:

! To display the contents of the manifest

1. Double-click MANIFEST.
The MANIFEST window appears, as follows:

2. Close the Manifest window, and then close ILDASM.

24 Module 2: Introduction to a Managed Execution Environment

Just-In-Time Compilation
Topic Objective
To describe JIT compilation
and introduce JIT compiler
options. ! Process for Code Execution
Lead-in # MSIL converted to native code as needed
MSIL code must be
converted into native code # Resulting native code stored for subsequent calls
before it can execute.
Because an intermediate # JIT compiler supplies the CPU-specific conversion
step is involved, the
common language runtime
optimizes the compilation
process for efficiency.

*ILLEGAL FOR NON-TRAINER USE**

As previously stated in this module, MSIL code must be converted into native
code before it can execute. Because an intermediate step is involved, the
common language runtime optimizes the compilation process for efficiency.

The Code Execution Process

The common language runtime compiles MSIL as needed. This just-in-time, or
JIT, compiling saves time and memory. The basic process is as follows:
1. When the common language runtime loads a class type, it attaches stub code
to each method.
2. For subsequent method calls, the stub directs program execution to the
common language runtime component that is responsible for compiling a
method’s MSIL into native code. This component of the common language
runtime is frequently referred to as the JIT compiler.
3. The JIT compiler compiles the MSIL and the method’s stub is substituted
with the address of the compiled code.
Future calls to that method will not involve the JIT compiler because the
compiled native code will simply execute.
Module 2: Introduction to a Managed Execution Environment 25

Application Domains
Topic Objective
To describe how application
domains provide application ! Historically, Process Boundaries Used to Isolate
isolation. Applications
Lead-in ! In the Common Language Runtime, Application
Historically, process
boundaries have been used
Domains Provide Isolation Between Applications
to isolate applications # The ability to verify code as type-safe enables isolation
running on the same
computer.
at a much lower performance cost
# Several application domains can run in a single process
! Faults in One Application Cannot Affect Other
Applications

*ILLEGAL FOR NON-TRAINER USE**

Historically, process boundaries have been used to isolate applications running
on the same computer. Each application is loaded into a separate process, which
isolates the application from other applications running on the same computer.
The applications are isolated because memory addresses are process-relative; a
memory pointer passed from one process to another cannot be used in any
meaningful way in the target process. In addition, you cannot make direct calls
between two processes. Instead, you must use proxies, which provide a level of
indirection.
Managed code must be passed through a verification process before it can be
run (unless the administrator has granted permission to skip the verification).
The verification process determines whether the code can attempt to access
invalid memory addresses or perform some other action that could cause the
process in which it is running to fail to operate properly.
Code that passes the verification test is said to be type-safe. The ability to verify
code as type-safe enables the common language runtime to provide as great a
level of isolation as the process boundary, at a much lower performance cost.
Application domains provide a secure and versatile unit of processing that the
common language runtime can use to provide isolation between applications.
You can run several application domains in a single process with the same level
of isolation that would exist in separate processes, but without incurring the
additional overhead of making cross-process calls or switching between
processes. The ability to run multiple applications within a single process
dramatically increases server scalability.
26 Module 2: Introduction to a Managed Execution Environment

Isolating applications is also important for application security. For example,

you can run controls from several Web applications in a single browser process
in such a way that the controls cannot access each other's data and resources.
The isolation provided by application domains has the following benefits:
! Faults in one application cannot affect other applications. Because type-safe
code cannot cause memory faults, using application domains ensures that
code running in one domain cannot affect other applications in the process.
! Individual applications can be stopped without stopping the entire process.
Using application domains enables you to unload the code running in a
single application.

Note You cannot unload individual assemblies or types. Only a complete

domain can be unloaded.

Code running in one application cannot directly access code or resources from
another application. The common language runtime enforces this isolation by
preventing direct calls between objects in different application domains.
Objects that pass between domains are either copied or accessed by proxy. If
the object is copied, the call to the object is local. That is, both the caller and the
object being referenced are in the same application domain. If the object is
accessed through a proxy, the call to the object is remote. In this case, the caller
and the object being referenced are in different application domains. Cross-
domain calls use the same remote call infrastructure as calls between two
processes or between two computers.
Module 2: Introduction to a Managed Execution Environment 27

Multimedia: Application Loading and Single-File Assembly

Execution
Topic Objective
To describe how assembly
code is executed.
Lead-in
In this demonstration, you
will see how a single-file
private assembly is loaded
and executed.

*ILLEGAL FOR NON-TRAINER USE**

Applications that are implemented by using MSIL code require the common
Delivery Tip language runtime to be installed on the user’s computer in order to run. The
To start the animation, click
the button in the lower-left
common language runtime manages the execution of code. For example, when
corner of the slide. The an application that is implemented as a single-file private assembly is run, the
animation plays following tasks are performed:
automatically. To pause or
rewind the animation, click
! The Microsoft Windows® loader loads the PE file.
the controls in the lower-left The PE file contains a call to a function found in the file MSCorEE.dll.
of the screen.
! Windows loads the file MSCorEE.dll and transfers control to it to initialize
the common language runtime.
! The common language runtime parses the metadata of the application
assembly, and then the JIT compiler compiles the code.
! The common language runtime then locates the PE file’s managed entry-
point (the Main method in the case of a C# program), and transfers control
to this entry point.

If the application calls a private assembly:

! The common language runtime uses probing to locate the referenced
assembly, beginning in the application’s root directory and then traversing
the subfolders until the assembly is located.
• If the assembly is not found, a TypeLoadException error occurs.
• If the assembly is found, it is loaded by the common language runtime.

The common language runtime loader parses the manifest in the referenced
assembly. The JIT compiler then compiles the required code in the assembly
and passes control to the called function.
28 Module 2: Introduction to a Managed Execution Environment

Garbage Collection
Topic Objective
To introduce memory and
resource management in
the .NET Framework. ! Garbage Collection Provides Automatic Object Memory
Management in the .NET Framework
Lead-in
Every program uses ! You No Longer Need to Track and Free Object Memory
resources, such as files,
screen space, network
connections, and database
resources.

*ILLEGAL FOR NON-TRAINER USE**

This topic introduces memory management in the .NET Framework.
For more information about memory and resource management, see Module 9,
“Memory and Resource Management,” in Course 2349B, Programming with
the Microsoft .NET Framework (Microsoft Visual C# .NET).

Current Memory Management Model

When you create an object programmatically, you generally follow these steps:
1. Allocate memory for the object
2. Initialize the memory
3. Use the object
4. Perform cleanup on the object
5. Free the object’s memory

If you forget to free memory when it is no longer required or try to use memory
after it has been freed, you can generate programming errors. The tracking and
correction of such errors are complicated tasks because the consequences of the
errors are unpredictable.

Memory Management in the .NET Framework

The common language runtime uses a heap called the managed heap to allocate
memory for all objects. This managed heap is similar to a C-Runtime heap,
however you never free objects from the managed heap. In the common
language runtime, garbage collection is used to manage memory deallocation.
The garbage collection process frees objects when they are no longer needed by
the application.
For more information about garbage collection, see Module 9, “Memory and
Resource Management,” in Course 2349B, Programming with the Microsoft
.NET Framework (Microsoft Visual C# .NET).
Module 2: Introduction to a Managed Execution Environment 29

Lab 2: Building a Simple .NET Application

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will learn
how to write, compile, and
run a simple application in
C# and how to use the MSIL
Disassembler to examine an
assembly.

*ILLEGAL FOR NON-TRAINER USE**

Objectives
After completing this lab, you will be able to:
! Write, compile, and run a simple application in C#.
! Use the MSIL Disassembler to examine an assembly.

Lab Setup
Only solution files are associated with this lab. The solution files for this lab are
in the folder <install folder>\Labs\Lab02\Solution.

Estimated time to complete this lab: 20 minutes

30 Module 2: Introduction to a Managed Execution Environment

Exercise 1
Creating the Program in C#
In this exercise, you will create the source code for a small console application
that takes user input and writes a string to the console by using C#. The lab uses
the classic Hello World application to allow you to focus on basic concepts in a
managed execution environment.
To help you concentrate on the syntactical aspects of this lab, you will use
Notepad to create and edit the source files. From a command prompt window,
you will then compile the application and test the resulting executable program.

! Write the source code

1. Open Notepad and create a class in C# called MainApp.
2. Import the System namespace.
3. Define the program entry point.
The entry point takes no arguments and does not return a value.
4. Create methods that accomplish the following:
a. Print the following text to the console: “Type your name and press
Enter”.
b. Read in the resulting user input.
c. Print the text “Hello” and append to the text the value that was read in.
5. Save the file as HelloLabCS.cs in the <install folder>\Labs\Lab02 folder.

! Build and test the program

Important To use Microsoft Visual Studio .NET tools within a command
prompt window, the command prompt window must have the proper
environment settings. The Visual Studio .NET Command Prompt window
provides such an environment. To run a Visual Studio .NET Command Prompt
window, click Start, All Programs, Microsoft Visual Studio .NET,
Visual Studio .NET Tools, and Visual Studio .NET Command Prompt.

1. From a Visual Studio .NET Command Prompt window, type the syntax to
build an executable program from HelloLabCS.cs.
2. Run the resulting executable program.
Your C# program should generate the following output:
Type your name and press Enter

When you press ENTER, the program outputs the text “Hello ” and
whatever text you typed as input.
Module 2: Introduction to a Managed Execution Environment 31

Exercise 2
Using the MSIL Disassembler
In this exercise, you will use the MSIL Disassembler to open a single assembly
and familiarize yourself with the assembly manifest.
In subsequent labs, you will explore assemblies in greater detail.

! Examine the metadata for the Hello World applications

1. Open a Visual Studio .NET Command Prompt window.
2. From the Visual Studio .NET Command Prompt window, type:
>ildasm /source

3. Open HelloLabCS.exe and double-click Manifest.

4. Note the following:
a. The externally referenced library named mscorlib
b. The assembly name HelloLabCS
c. Version information (for the HelloLabCS assembly and mscorlib)
5. Close the Manifest window, double-click MainApp, double-click Main,
and view the MSIL and source code.
32 Module 2: Introduction to a Managed Execution Environment

Review
Topic Objective
To reinforce module
objectives by reviewing
key points. ! Writing a .NET Application
Lead-in ! Compiling and Running a .NET Application
The review questions cover
some of the key concepts
taught in the module.

*ILLEGAL FOR NON-TRAINER USE**

1. Name the root namespace for types in the .NET Framework.
The System namespace is the root namespace for types in the .NET
Framework.

2. What class and methods can your application use to input and output to the
console?
You can use the common language runtime’s Console class of the
System namespace for input and output to the console of any string or
numeric value by using the Read, ReadLine, Write, and WriteLine
methods.

3. When compiling code that makes references to classes in assemblies other

than mscorlib.dll what must you do?
You must use the /reference compilation switch. The /reference
compilation option allows the compiler to make information in the
specified libraries available to the source that is currently being
compiled. The /r switch is equivalent to /reference.

4. What is the code produced by a .NET compiler called?

Microsoft intermediate language (MSIL), sometimes called managed
code.
Module 2: Introduction to a Managed Execution Environment 33

5. What .NET component compiles MSIL into CPU specific native code?
The just-in-time (JIT) compiler.

6. What feature of .NET ensures that object memory is freed?

The garbage collection process.
THIS PAGE INTENTIONALLY LEFT BLANK
Module 3: Working with
Components

Contents

Overview 1
An Introduction to Key .NET Framework
Development Technologies 2
Creating a Simple .NET Framework
Component 4
Lab 3.1: Creating a .NET Framework
Component 11
Creating a Simple Console Client 14
Lab 3.2: Creating a Simple Console-Based
Client 19
Demonstration: Creating a Windows
Forms Client 22
Creating an ASP.NET Client 27
Lab 3.3: Calling a Component Through
an ASP.NET Page 36
Review 40
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, place or event is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

 2001-2002 Microsoft Corporation. All rights reserved.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Module 3: Working with Components iii

Instructor Notes
Presentation: After completing this module, students will be able to:
70 Minutes
! Create a simple Microsoft® .NET Framework component in C#.
Lab: ! Implement structured exception handling.
60 Minutes
! Create a simple .NET Framework console application that calls a
component.
! Create a .NET Framework client application by using the Windows Forms
library.
! Create an ASP.NET page that uses the previously developed .NET
Framework component to create an ASP.NET application.

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach
this module.

Required Materials
To teach this module, you need the Microsoft PowerPoint® file 2349B_03.ppt.

Preparation Tasks
To prepare for this module, you should:
! Read all of the materials for this module.
! Practice the demonstration.
! Review the animation.
! Complete the lab.
iv Module 3: Working with Components

Demonstrations
This section provides demonstration procedures that will not fit in the margin
notes or are not appropriate for the student notes.

Creating a Windows Forms Client

This demonstration shows how to build a simple Windows Forms client in
Microsoft Visual Studio® .NET. If time permits, you can show the
demonstration by using Microsoft Visual Basic®. The solution code for this
demonstration is located in <install folder>\DemoCode\Mod03\C# and
<install folder>\DemoCode\Mod03\VB.
In this demonstration, point out how the Windows Form is created in the Main
method. Also, point out how the Windows Forms Designer adds code to create
and initialize the controls. Consider stepping through the code to explain the
code to students.

! To create a Windows Form

1. Open Visual Studio .NET and create a Microsoft Visual C#™ project from
the Windows Application template. Name the project WinForm_Client.
2. Add two buttons and a listbox to the form. Set the following properties.
a. Set the button1 Text property to &Execute.
b. Set the button2 Text property to &Close.
c. Set the Form1 Text property to Client.

! To add references
1. On the Project menu, click Add Reference.
2. In the Add Reference dialog box, click the Browse button.
3. Select the CompCS.dll and CompVB.dll assemblies as references. These
assemblies are located in <install folder>\DemoCode\Mod03\C#. Then click
the Open button.
4. Click OK.
5. Add references to the assemblies in the form code. Use aliases to avoid
name conflicts.
using CSStringComp = CompCS.StringComponent;
using VBStringComp = CompVB.StringComponent;
Module 3: Working with Components v

! To add button event handlers

1. In the form, double-click the Execute button to create a button-click event
handler.
2. Add the following code to the event handler to create an instance of the C#
component and Visual Basic component, and add their strings to the listbox.
//Local Variables
CSStringComp myCompCS = new CSStringComp();
VBStringComp myCompVB = new VBStringComp();
int stringCount=0;

//Display results from C# Component

for (stringCount=0; stringCount<myCompCS.Count;!
stringCount++)
{
listBox1.Items.Add(myCompCS.GetString(stringCount));
}

//Display results from Visual Basic Component

for (stringCount=0; stringCount<myCompVB.Count;!
stringCount++)
{
listBox1.Items.Add(myCompVB.GetString(stringCount));
}

3. In the form, double-click the Close button to create a button-click event

handler.
4. In the Close button event handler, call the Close method to close the form.
5. Compile and run the application. When you click the Execute button, the
list box should be filled with four C# strings and four Visual Basic strings.

Testing the ASP.NET Client

To test the ASP.NET page, the following software must be installed on the test
computer:
! Microsoft Internet Information Services (IIS)
! The .NET Framework common language runtime
! The .aspx file that contains the client code
! All compiled components that are required by the client application

You must configure a virtual directory that points to the directory that contains
the .aspx file. You can use the New Directory Wizard in the IIS snap-in to do
this.
vi Module 3: Working with Components

! To configure a virtual directory

1. Click the Start menu, click Control Panel, click Performance and
Maintenance, click Administrative Tools, and then click Internet
Information Services.
2. Expand the computer icon, expand the Web Sites folder, and then expand
and select Default Web Site.
3. On the Action menu, point to New, and then click Virtual Directory.
The Virtual Directory Creation Wizard is launched.
4. Click Next to continue.
5. In the Alias text box, type Test and click Next.
6. Browse to the <install folder>\Labs\Lab03.3\SOLUTION\ASP.NET_Client
folder that contains the file ClientASP.NET.aspx, click OK, and then click
Next.
7. On the Access Permissions page, accept the default selections, click Next,
and then click Finish.
The Test folder is added to the Default Web Site.
Ensure that the compiled component DLLs, CompCS.dll and CompVB.dll,
are in a \Bin subdirectory under the starting point for the application virtual
directory.
Module 3: Working with Components vii

! To test the ASP.NET Client

• Open Microsoft Internet Explorer, and type the following text in the
Address bar:
http://localhost/Test/ClientASP.NET.aspx
When you press ENTER, the following display, or one similar to it, appears.

Multimedia
This section lists the multimedia items that are part of this module. Instructions
for launching and playing the multimedia are included with the relevant slides.

ASP.NET Execution Model

This animation will show students how ASP.NET pages are processed on the
server.
viii Module 3: Working with Components

Module Strategy
Use the following strategy to present this module:
! An Introduction to Key .NET Framework Technologies
Briefly introduce Windows Forms, Web Forms, and XML Web services.
Explain that you will show an example of a Windows Form in this module.
Tell students that they will learn about XML Web services in Module 13,
“Remoting and XML Web Services,” in Course 2349B, Programming with
the Microsoft .NET Framework (Microsoft Visual C# .NET).
! Creating a Simple .NET Framework Component
Show the basic approach to creating reusable classes by using C# and
Visual Basic. Spend some time on the new structured exception handling
techniques. Use the command line to compile the component.
Break the lecture at this point and instruct students to do Lab 3.1, Creating a
.NET Framework Component.
! Creating a Simple Console Client
Show how to write a simple console application that calls the .NET
Framework runtime-compatible component that was created in Creating a
Simple .NET Framework Component. Be sure to fully explain how to use a
namespace alias to remove ambiguity to type references.
Instruct students to do Lab 3.2, Creating a Simple Console-Based Client.
! Creating an ASP.NET Client
Emphasize the .NET Framework’s capability to execute the component
code that was created in Creating a Simple .NET Framework Component in
a variety of environments. Contrast the use of the component by the stand-
alone client applications with that of an IIS ASP.NET page.
Be sure to present the ASP.NET Execution Model animation to help
students understand how ASP.NET pages are processed on the server.
Instructions for running the animation are included in the Instructor Notes in
the margins.
The main objective of this section is to show students how to use an
ASP.NET page to obtain the string data from the .NET Framework
component, to format that data in HTML, and to return this HTML to a Web
browser for display.
Be sure to demonstrate how to test the ASP.NET page that was created in
Creating an ASP.NET Client in this module. Students must understand how
to configure a virtual directory that points to the directory that contains the
.aspx file.
Instruct students to do Lab 3.3, Calling a Component Through an ASP.NET
Page.
Module 3: Working with Components 1

Overview
Topic Objective
To provide an overview of
the module topics and
objectives.
! An Introduction to Key .NET Framework
Development Technologies
Lead-in
In this module, you will learn ! Creating a Simple .NET Framework Component
how to create a small
client/server application. ! Creating a Simple Console Client
! Creating an ASP.NET Client

*ILLEGAL FOR NON-TRAINER USE**

In this module, you will learn how to create a small client/server application in
For Your Information C#. The steps that are necessary to construct, compile, and run each program
Tell students that the code
examples used in this
are covered in detail. You will also learn how to build the client application by
module are from the tutorial, using the Windows Forms library and an ASP.NET page.
“Introduction to Developing
As in Module 2, “Introduction to a Managed Execution Environment” in
with the .NET Framework.”
This tutorial is found in the
Course 2349B, Programming with the Microsoft .NET Framework (Microsoft
.NET Framework Software Visual C#™ .NET), the content of this module is based on the “Introduction to
Development Kit (SDK). Developing with the .NET Framework” tutorial in the .NET Framework
Software Development Kit (SDK).
After completing this module, you will be able to:
! Create a simple Microsoft® .NET Framework component in C#.
! Implement structured exception handling.
! Create a simple .NET Framework console application that calls a
component.
! Create a .NET Framework client application by using the Windows Forms
library.
! Create an ASP.NET page that uses the previously developed .NET
Framework component to create an ASP.NET application.
2 Module 3: Working with Components

An Introduction to Key .NET Framework Development

Technologies
Topic Objective
To introduce the
technologies that are
used to develop .NET ! Windows Forms
Framework applications.
! Web Forms
Lead-in
To develop applications in ! XML Web Services
the .NET Framework, you
should be familiar with
Windows Forms, ASP.NET
Web Forms, and XML Web
services.

*ILLEGAL FOR NON-TRAINER USE**

To develop applications in the .NET Framework, you should be familiar with
the following technologies: Windows Forms, ASP.NET Web Forms, and XML
Web services. Your choice of technology, or technologies, depends on the type
of software solution that you wish to implement. This topic briefly introduces
the technologies and provides references to additional information.

Windows Forms
Windows Forms are used to develop applications in which the client computer
handles most of the application processing. Classic Microsoft Win32® desktop
applications, such as drawing and graphics applications, data-entry systems,
point-of-sale systems, and games, are well suited to Window Forms. All of
these applications rely on the power of the desktop computer for processing and
for high-performance content display.
The System.Windows.Forms namespace contains the classes used to create
Windows Forms.
Module 3: Working with Components 3

Web Forms
ASP.NET Web Forms are used to create applications in which the primary user
interface is a browser. Obviously, you can use Web Forms to create
applications that are available on the World Wide Web, such as e-commerce
applications, but you will also find them helpful for creating other types of
applications, such as intranet applications, which users can run by using only
their browser, which is already installed on their computers.
Because Web Forms applications are platform-independent, users can interact
with your application regardless of the type of browser or computer that they
are using. You can also optimize Web Forms applications to use features that
are built into the most recent browsers, such as Dynamic Hypertext Markup
Language (DHTML) and HTML 4.0, which enhance performance and
responsiveness.
The System.Web namespace contains the classes used to create Web Forms.
For more information about Windows Forms and ASP.NET Web Forms, see
“Windows Forms and Web Forms Recommendations” in the .NET Framework
SDK documentation.

XML Web Services

An XML Web Service is a programmable entity that resides on a Web server
and is exposed through standard Internet protocols. In many respects, the
programming model for creating and using XML Web services is similar to the
programming model for creating and using COM-based components.
However, unlike COM, the XML Web services programming model is based
on simple, open standards that are broadly supported. Instead of using binary
communication methods between applications, XML Web services use
communication based on the SOAP protocol to transport XML messages
between applications. In an environment of integrated, programmable XML
Web services, XML is the universal language for communication of raw data
and information that can be understood and acted upon.
For more information about XML Web services, see Module 13, “Remoting
and XML Web Services” in Course 2349B, Programming with the Microsoft
.NET Framework (Microsoft Visual C# .NET).
4 Module 3: Working with Components

" Creating a Simple .NET Framework Component

Topic Objective
To provide an overview of
the section topics.
! Using Namespaces and Declaring the Class
Lead-in
In this section, you will learn ! Creating the Class Implementation
how to use C# to create a
simple component. ! Implementing Structured Exception Handling
! Creating a Property
! Compiling the Component

*ILLEGAL FOR NON-TRAINER USE**

In this section, you will learn how to create a simple component using C#. The
component provides a wrapper for an array of strings and includes a GetString
method that takes an integer and returns a string. The component includes a
read-only Count property that contains the number of elements in the string
array, which is used to iterate over all of the array members. The GetString
method also demonstrates the use of structured exception handling.
In subsequent sections of this module, you will learn how clients use the
Delivery Tip GetString method and the Count property to determine and display the output
If you prefer, you can use
Notepad to demonstrate the
from the component’s string array.
code in this section, instead The simple string component that is described in this section shows the basic
of discussing the content of
approach to creating reusable classes in C#.
each slide.
Module 3: Working with Components 5

Using Namespaces and Declaring the Class

Topic Objective
To explain how to create a
new namespace that
encapsulates classes. ! Create a New Namespace
Lead-in using
To create a new namespace using System;
System;
that encapsulates the
namespace
namespace CompCS
CompCS {...}
{...}
classes that you will be
creating, you use the
namespace statement.
! Declare the Class

public
public class
class StringComponent
StringComponent {...}
{...}

*ILLEGAL FOR NON-TRAINER USE**

To create a new namespace that encapsulates the classes that you will be
creating, you use the namespace statement, as in the following example:
using System;

namespace CompCS {...}

The following statement denotes that instances of the StringComponent class

will now be created by the runtime and managed in the garbage-collected heap.
public class StringComponent {...}
6 Module 3: Working with Components

Creating the Class Implementation

Topic Objective
To explain how to create the
! Declare a Private Field of Type Array of String Elements
class implementation.
Lead-in private
private string[]
string[] stringSet;
stringSet;
The component provides a
wrapper for an array of ! Create a Public Default Constructor
strings. public
public StringComponent()
StringComponent() {...}
{...}
! Assign the stringSet Field to an Array of Strings
stringSet
stringSet == new
new string[]
string[] {{
"C# String 0",
"C# String 0",
"C#
"C# String
String 1",
1",
...
...
};
};

*ILLEGAL FOR NON-TRAINER USE**

The component provides a wrapper for an array of strings. You can declare a
private field of type array of string elements, as in the following example:
private string[ ] stringSet;

The following example shows how to create a public default constructor, which
executes each time a new instance of the class is created, and how to assign the
stringSet field to an array of strings:
public StringComponent() {
stringSet = new string[ ] {
"C# String 0",
"C# String 1",
"C# String 2",
"C# String 3"
};
}

In the preceding example, you can see that the constructor has the same name as
the class and does not have a return type.
Module 3: Working with Components 7

Implementing Structured Exception Handling

Topic Objective
To explain how to ! Implement the GetString Method
implement structured
exception handling. public
public string
string GetString(int
GetString(int index)
index) {...}
{...}
Lead-in
The component uses the ! Create and Throw a New Object of Type
GetString method to return IndexOutOfRangeException
the strings in the stringSet
array. if((index
if((index << 0)
0) ||
|| (index
(index >=
>= stringSet.Length))
stringSet.Length)) {{
throw
throw new
new IndexOutOfRangeException();
IndexOutOfRangeException();
}}
return
return stringSet[index];
stringSet[index];
! Exceptions Caught by the Caller Using a try/catch/finally Statement
! Structured Exception Handling Replaces HRESULT-Based Error
Handling in COM

*ILLEGAL FOR NON-TRAINER USE**

Programs must be able to uniformly handle errors and exceptions that occur
during execution. The common language runtime helps you design error-
tolerant software by providing a platform for notifying programs of errors in a
uniform manner. All .NET Framework methods indicate failure by throwing
exceptions.
Traditionally, a language’s error-handling model relied on either the language’s
unique way of detecting errors and locating handlers for them, or on the error-
handling mechanism that is provided by the operating system. The runtime
implements exception handling with the following features:
! It handles exceptions without regard for the language that generates the
exception or the language that will be called upon to handles the exception.
! It does not require any particular language syntax for handling exceptions,
but allows each language to define its own syntax.
! It allows exceptions to be thrown across process boundaries and machine
boundaries.

Exceptions offer several advantages over other methods of error notification.

Failures do not go unnoticed. Invalid values do not continue to propagate
through the system. You do not have to check return codes. Exception-handling
code can be easily added to increase program reliability. Finally, the runtime’s
exception handling is faster than Windows-based C++ error handling.
8 Module 3: Working with Components

The component uses the GetString method to return the strings in the stringSet
array. You can use a throw statement to implement structured exception
handling within the GetString method, as in the following example:
public string GetString(int index) {
if ((index < 0) || (index >= stringSet.Length)) {
throw new IndexOutOfRangeException();
}
return stringSet[index];
}

In the preceding example, the program evaluates whether the integer that is
passed as an argument to GetString is a valid index for the stringSet array. If
the index is invalid, the following statement creates and throws a new object of
type IndexOutOfRangeException:
throw new IndexOutOfRangeException();

If the index is valid, the program returns the string element of the stringSet
array at that particular index.
Exceptions may be caught by the caller by using a try/catch/finally statement.
Place the sections of code that might throw exceptions in a try block and place
code that handles exceptions in a catch block. You can also write a finally block
that always runs regardless of how the try block runs. The finally block is
useful for cleaning up resources after a try block. For example, in C#:
try {
// code that might throw exceptions
}
catch(Exception e) {
// place code that handles exceptions
}
finally {
// place code that runs after try or catch runs
}

In general, it is good programming practice to catch a specific type of exception

rather than using the preceding general catch statement that catches any
exception.
Structured exception handling replaces the HRESULT-based error-handling
system that is used in COM. All .NET Framework exception-handling classes,
such as IndexOutOfRangeException and user-defined exceptions, must derive
from System.Exception.
For more information about exception handling, see “Handling and Throwing
Exceptions” in the .NET Framework SDK documentation.
Module 3: Working with Components 9

Creating a Property
Topic Objective
To explain how to create a
property.
! Create a Read-Only Count Property to Get the Number
Lead-in of String Elements in the stringSet Array
To provide the number of
string elements in the
stringSet array in C#, you
public
public int
int Count
Count {{
create a read-only property
called Count. get
get {{ return
return stringSet.Length;
stringSet.Length; }}
}}

*ILLEGAL FOR NON-TRAINER USE**

To provide the number of string elements in the stringSet array, you create a
read-only property called Count, as in the following example:
public int Count {
get { return stringSet.Length; }
}

For Your Information

Point out that the GetString
method and Count property
may be used by a client to
iterate over the component’s
string elements. This
information will help
students when they create
the clients in subsequent
labs.
10 Module 3: Working with Components

Compiling the Component

Topic Objective
To explain how to compile
the source code for a
component. ! Use the /target:library Switch to Create a DLL
Lead-in # Otherwise, an executable with a .dll file extension is
To compile the source code, created instead of a DLL library
first you must save the
source file.
csc
csc /out:CompCS.dll
/out:CompCS.dll /target:library
/target:library CompCS.cs
CompCS.cs

*ILLEGAL FOR NON-TRAINER USE**

To compile the source code for the C# component, first you must save the
source file, and then enter the following command from a command prompt
window:

Important To use Microsoft Visual Studio® .NET tools within a command

csc /out:CompCS.dll /target:library CompCS.cs

This command directs the compiler to produce the file CompCS.dll. The
/target:library switch is required to actually create a DLL library, instead of an
executable.
Module 3: Working with Components 11

Lab 3.1: Creating a .NET Framework Component

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will learn
how to create a simple
.NET Framework
component in C#.

*ILLEGAL FOR NON-TRAINER USE**

For Your Information Objective

In this introductory module,
After completing this lab, you will be able to create a simple .NET Framework
the lab problems have
intentionally been made
component in C#.
very similar to the problems
presented in the module. Lab Setup
This approach is designed
Only solution files are associated with this lab. The solution files for this lab are
to allow the student to
experience a wide range of
in the folder <install folder>\Labs\Lab03.1\Solution.
.NET software approaches
within a very limited amount Scenario
of time.
This lab is based on a small client server application scenario in which you
write both the client application and server component using C#.
This lab focuses on building the server component.
Lab 3.2, “Creating a Simple Console-Based Client,” focuses on building a
client program that calls the server component.

Estimated time to complete this lab: 15 minutes

12 Module 3: Working with Components

Exercise 1
Creating a Component in C#
In this exercise, you will use C# to create a component that provides a wrapper
for a private array of strings. The wrapper includes a read-only Count property,
which returns the number of strings in the array, and a public GetString
method, which takes an integer argument and returns the string in the private
array at that index. The GetString method will also implement structured
exception handling to ensure that the argument of the index is within range of
the array.

! Specify namespace information and class declarations

1. Open Notepad and reference the System namespace.
2. Create a new namespace named CompCS.
CompCS will contain the class for your component.

! Create the class implementation

1. Create a public class named StringComponent.
2. Declare a private field named StringSet of type array of string elements.
3. Create a public default constructor.
The default constructor takes no arguments.
4. Assign to the field StringSet an array of strings initialized with the
following four strings:
"C# String 0",
"C# String 1",
"C# String 2",
"C# String 3"

5. Create the public GetString method, which takes an integer as an argument.

That integer must be a valid index for the StringSet array.
a. If the integer is an invalid index, throw an index out of range exception.
b. If the integer is a valid index, return the StringSet string at that index.
6. Create a read-only Count property that gets the number of string elements
in the StringSet array.
7. Save the file as CompCS.cs in the <install folder>\Labs\Lab03.1 folder.
Module 3: Working with Components 13

! Compile the source code

• From a Visual Studio .NET command prompt window, enter the command
to build a library named CompCS.dll from the CompCS.cs. source. You
must specify that the target is a library.
14 Module 3: Working with Components

" Creating a Simple Console Client

Topic Objective
To provide an overview of
the section topics.
! Using the Libraries
Lead-in
In this section, you will learn ! Instantiating the Component
how to write a simple
console application that ! Calling the Component
calls a .NET Framework
runtime-compatible ! Building the Client
component.

*ILLEGAL FOR NON-TRAINER USE**

In this section, you will learn how to write a simple console application that
calls the .NET Framework runtime-compatible component that was created in
the previous section.
Module 3: Working with Components 15

Using the Libraries

Topic Objective
To explain how to import
libraries and to use ! Reference Types Without Having to Fully Qualify the
namespace aliasing to Type Name
remove ambiguity.
using
using CompCS;
CompCS;
Lead-in
By using the namespaces in using
using CompVB;
CompVB;
the program, you can
reference types in the library ! If Multiple Namespaces Contain the Same Type Name,
without fully qualifying the Create a Namespace Alias to Remove Ambiguity
type name.
using
using CSStringComp
CSStringComp == CompCS.StringComponent;
CompCS.StringComponent;

using
using VBStringComp
VBStringComp == CompVB.StringComponent;
CompVB.StringComponent;

*ILLEGAL FOR NON-TRAINER USE**

This topic explains how to reference types in your applications by using
namespaces and how to use a namespace alias if you need to remove ambiguity
to type references.

Using the Namespaces

By using the namespaces in the program, you can reference types in the library
without fully qualifying the type name.
To use the component namespaces in C#, you must enter a using statement
followed by the name of the component namespaces:
using CompCS;
using CompVB;

Using an Alias
Consider a scenario where similar C# and Microsoft Visual Basic® components
use the same type name (StringComponent). You must still fully qualify the
type name to remove any ambiguity when referring to the GetString method
and the Count property. In C#, you can create and use aliases to solve this
problem.
The following C# example shows how to alias the component namespaces so
that you do not have to fully qualify the type names:
using CSStringComp = CompCS.StringComponent;
using VBStringComp = CompVB.StringComponent;
16 Module 3: Working with Components

Instantiating the Component

Topic Objective
To describe how to
instantiate the component
in C#. ! Declare a Local Variable of Type StringComponent
Lead-in ! Create a New Instance of the StringComponent Class
To instantiate the
StringComponent class,
you declare a local variable //…
//…
of type StringComponent using
using CSStringComp
CSStringComp == CompCS.StringComponent;
CompCS.StringComponent;
and create a new instance //…
//…
of StringComponent. CSStringComp
CSStringComp myCSStringComp
myCSStringComp == new
new
CSStringComp();
CSStringComp();

*ILLEGAL FOR NON-TRAINER USE**

To instantiate the StringComponent class, you declare a local variable of type
StringComponent and create a new instance of StringComponent, as in the
following example:
//…
using CSStringComp = CompCS.StringComponent;

class MainApp
{
public static void Main() {

CSStringComp myCSStringComp = new CSStringComp();

//…
}
}
Module 3: Working with Components 17

Calling the Component

Topic Objective
To describe how to call a
component after it has been
instantiated. ! Iterate over All the Members of StringComponent and
Output the Strings to the Console
Lead-in
After instantiating the
StringComponent class, for
for (int
(int index
index == 0;
0;
the client can iterate over index
the string array in the C# or index << myCSStringComp.Count;
myCSStringComp.Count; index++)
index++) {{
Console.WriteLine
Console.WriteLine
Visual Basic component and (myCSStringComp.GetString(index));
return the appropriate (myCSStringComp.GetString(index));
}}
output.

*ILLEGAL FOR NON-TRAINER USE**

After instantiating the StringComponent class, the client can iterate over the
string array in the component and return the appropriate output, as in the
following example:
using System;
using CSStringComp = CompCS.StringComponent;

class MainApp
{
public static void Main() {

CSStringComp myCSStringComp = new CSStringComp();

// Display result strings from CS component
Console.WriteLine("Strings from CS StringComponent");
for (int index = 0; index < myCSStringComp.Count;
index++) {
Console.WriteLine(myCSStringComp.GetString(index));
}
}
}
18 Module 3: Working with Components

Building the Client

Topic Objective
To show how to build the
client in C#.
! Use the /reference Switch to Reference the Assemblies
Lead-in That Contain the StringComponent Class
To build the client, you can
compile the source code
from a command prompt csc
window. csc /reference:CompCS.dll,CompVB.dll!
/reference:CompCS.dll,CompVB.dll!
/out:ClientCS.exe
/out:ClientCS.exe ClientCS.cs
ClientCS.cs

*ILLEGAL FOR NON-TRAINER USE**

To build the client, you can compile the source code from a command prompt
window. You must use the /reference option to reference all of the assemblies
that contain the StringComponent class, as in the following example:
csc /reference:CompCS.dll,CompVB.dll!
/out:ClientCS.exe ClientCS.cs

Running a client program that first iterates over the C# component’s strings and
then iterates over the Visual Basic component’s strings will produce the
following output:
Strings from C# StringComponent
C# String 0
C# String 1
C# String 2
C# String 3

Strings from VB StringComponent

VB String 0
VB String 1
VB String 2
VB String 3
Module 3: Working with Components 19

Lab 3.2: Creating a Simple Console-Based Client

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will learn
how to create a simple
console-based client
application that calls a
component.

*ILLEGAL FOR NON-TRAINER USE**

Objectives
After completing this lab, you will be able to create a simple console-based
client application that calls a component.

Lab Setup
To complete this lab you will need the solution files from Lab 3.1 and a
Visual Basic component provided for you in the <install folder>\Labs\Lab03.2\
Starter\VB\Component folder. The solution files for this lab are located in
<install folder>\Labs\Lab03.2\Solution.

Scenario
This lab is based on a small client/server application scenario in which both the
client application and server component are written by using C#.
This lab focuses on building a simple console-based client application that calls
the component that was created in Lab 3.1, “Creating a .NET Framework
Component.” Also, another version of the component written in Visual Basic is
provided. The client will use both the C# and Visual Basic component versions
to show cross-language compatibility.

Estimated time to complete this lab: 15 minutes

20 Module 3: Working with Components

Exercise 1
Creating a Client Application in C#
In this exercise, you will create a simple console application to call the C#
component that you created in Lab 3.1, “Creating a .NET Framework
Component,” and a Visual Basic component that is already provided. The
Visual Basic component provides the same StringComponent class as the C#
component.

! Specify namespace information

1. Open Notepad and import the System namespace.
2. Use the namespace of the C# component that you created in Lab 3.1,
“Creating a .NET Framework Component.”
3. Use the namespace of the Visual Basic component. The namespace of the
Visual Basic component is CompVB.
Because you are importing two libraries that contain the same type name but
have different namespaces, use an alias directive to allow for unambiguous
references to StringComponent classes.
4. Create a class in C# called MainApp.
5. Specify the program entry point.
The entry point takes no arguments and does not return a value.

! Write the code to call the C# and Visual Basic components

1. Assign to a local variable named myCSStringComp a new instance of the
C# version of StringComponent.
2. Write the code to print the following string to the console:
Strings from C# StringComponent

3. Iterate over all of the members of the C# string component and output the
strings to the console.
4. Repeat steps 1 through 3 for the Visual Basic version of StringComponent.
Name the local variable myVBStringComp.
5. Save the file as ClientCS.cs in the <install folder>\Labs\Lab03.2 folder.
Module 3: Working with Components 21

! Compile and run the program

1. From a Visual Studio .NET command prompt window, enter the command
to build the executable program ClientCS.exe from ClientCS.cs. You must
reference the assemblies that contain the C# and Visual Basic
StringComponent class. You should copy these assemblies into the same
directory as ClientCS.cs. The Visual Basic assembly is located in
<install folder>\Labs\Lab03.2\Starter\VB\Component. The C# assembly is
located in <install folder>\Labs\Lab03.1\Solution\C#\Component.
2. Run the resulting executable program.
Your C# program should generate the following output:
Strings from C# StringComponent
C# String 0
C# String 1
C# String 2
C# String 3

Strings from VB StringComponent

VB String 0
VB String 1
VB String 2
VB String 3
22 Module 3: Working with Components

Demonstration: Creating a Windows Forms Client

Topic Objective
To demonstrate how to
create a Windows Forms
client.
Lead-in
In this demonstration, you
will see how to create a
Windows Forms client.

*ILLEGAL FOR NON-TRAINER USE**

In previous sections of this course, all examples have been command-line
programs that wrote to the system console. In this demonstration, you will learn
how to rewrite the client application so it can use the new .NET Windows
Forms library, which is available to all .NET Framework runtime-compatible
languages. In this demonstration, the client displays in a list box on a form the
string output that was displayed in the system console in previous examples.
Module 3: Working with Components 23

using System;
using System.Drawing;
using System.Collections;
using System.ComponentModel;
using System.Windows.Forms;
using System.Data;

using CSStringComp = CompCS.StringComponent;

using VBStringComp = CompVB.StringComponent;

namespace WinForm_Client
{
public class Form1 : System.Windows.Forms.Form
{
private System.Windows.Forms.Button button1;
private System.Windows.Forms.Button button2;
private System.Windows.Forms.ListBox listBox1;
/// <summary>
/// Required designer variable.
/// </summary>
private System.ComponentModel.Container components =
null;

public Form1()
{
//
// Required for Windows Form Designer support
//
InitializeComponent();

/// <summary>
/// Clean up any resources being used.
/// </summary>
protected override void Dispose( bool disposing )
{
if( disposing )
{
if (components != null)
{
components.Dispose();
}
}
base.Dispose( disposing );
}

(Code continued on the following page.)

24 Module 3: Working with Components

#region Windows Form Designer generated code

/// <summary>
/// Required method for Designer support - do not modify
/// the contents of this method with the code editor.
/// </summary>
private void InitializeComponent()
{
this.button1 = new System.Windows.Forms.Button();
this.button2 = new System.Windows.Forms.Button();
this.listBox1 = new System.Windows.Forms.ListBox();
this.SuspendLayout();
//
// button1
//
this.button1.Location = new System.Drawing.Point(24,
232);
this.button1.Name = "button1";
this.button1.Size = new System.Drawing.Size(64, 24);
this.button1.TabIndex = 0;
this.button1.Text = "&Execute";
this.button1.Click += new
System.EventHandler(this.button1_Click);
//
// button2
//
this.button2.Location = new
System.Drawing.Point(192, 232);
this.button2.Name = "button2";
this.button2.Size = new System.Drawing.Size(64, 24);
this.button2.TabIndex = 1;
this.button2.Text = "&Close";
this.button2.Click += new
System.EventHandler(this.button2_Click);
//
// listBox1
//
this.listBox1.Location = new System.Drawing.Point(8,
8);
this.listBox1.Name = "listBox1";
this.listBox1.Size = new System.Drawing.Size(264,
199);
this.listBox1.TabIndex = 2;
//
(Code continued on the following page.)
Module 3: Working with Components 25

// Form1
//
this.AutoScaleBaseSize = new System.Drawing.Size(5,
13);
this.ClientSize = new System.Drawing.Size(292, 273);
this.Controls.AddRange(new
System.Windows.Forms.Control[] {
this.listBox1,
this.button2,
this.button1});
this.Name = "Form1";
this.Text = "Client";
this.ResumeLayout(false);

}
#endregion

/// <summary>
/// The main entry point for the application.
/// </summary>
[STAThread]
static void Main()
{
Application.Run(new Form1());
}

private void button1_Click(object sender,

System.EventArgs e)
{
//Local Variables
CSStringComp myCompCS = new CSStringComp();
VBStringComp myCompVB = new VBStringComp();
int stringCount=0;

//Display results from C# Component

for (stringCount=0;
stringCount<myCompCS.Count;stringCount++)
{
listBox1.Items.Add(
myCompCS.GetString(stringCount));
}

(Code continued on the following page.)

26 Module 3: Working with Components

//Display results from Visual Basic Component

for (stringCount=0;
stringCount<myCompVB.Count;stringCount++)
{
listBox1.Items.Add(
myCompVB.GetString(stringCount));
}
}

private void button2_Click(object sender,

System.EventArgs e)
{
Close();
}
}
}
Module 3: Working with Components 27

" Creating an ASP.NET Client

Topic Objective
To provide an overview of
the section topics.
! Writing the HTML for the ASP.NET Application
Lead-in
In this section, you will learn ! Coding the Page_Load Event Handler
how to use an ASP.NET
page to obtain the string ! Generating the HTML Response
data from the .NET
Framework component, to
format the data in HTML,
and to return this HTML to a
Web browser for display.

*ILLEGAL FOR NON-TRAINER USE**

In this module, you have learned how to create two stand-alone versions of a
client application that calls the simple string component: a console application
and a form based on the Windows Forms library.
Another important feature of the .NET Framework is the capability to execute
the component code that was used by such stand-alone client applications in a
Microsoft Internet Information Services (IIS) ASP.NET page.
In this section, you will learn how to use an ASP.NET page to obtain the string
data from the .NET Framework component, to format that data in HTML, and
to return this HTML to a Web browser for display.
28 Module 3: Working with Components

Multimedia: ASP.NET Execution Model

Topic Objective
To describe the ASP.NET
execution model.
Lead-in
In this animation, you will
see how ASP.NET pages
are processed on the
server.

*ILLEGAL FOR NON-TRAINER USE**

To launch the animation, The .NET Framework provides the capability to execute code that was used in
click the button in the lower- the preceding stand-alone client applications in an ASP.NET page. However,
left corner of the slide. To there are some differences in the code execution processes.
play the animation, click the
Start button, and then click An ASP.NET page generally produces HTML in response to a HTTP request;
the First Request, Second and the page itself is compiled dynamically, unlike the stand-alone client
Request, and Output Cache applications. Each ASP.NET page is individually parsed, and the syntax is
buttons at the top of the checked. Then, a .NET runtime class is produced, compiled, and invoked.
screen. There is no audio, ASP.NET caches the compiled object, so subsequent requests do not perform
but explanatory text appears the parse and compile step and thus execute much faster.
in the Info column when you
click one of the buttons. In this animation, you will see how ASP.NET pages are processed on the
server. To view the animation, open the 2349B_mod3.htm file from the Media
folder.
Tell students that they can
view the animation again
later for themselves by
opening the
2349B_mod3.htm file from
the Media folder.
Module 3: Working with Components 29

Writing the HTML for the ASP.NET Application

Topic Objective
To describe how to write the ! Specify Page-Specific Attributes Within a Page Directive
HTML for an ASP.NET
application. <%@
<%@ Page
Page Language="C#"
Language="C#" Description="ASP.NET
Description="ASP.NET Client"
Client" %>
%>
Lead-in
An ASP.NET file is a text file ! Import the Namespace and the Physical Assembly
that contains markup syntax
for coding server-side page <%@
logic, dynamic output, and <%@ Import
Import Namespace="CompCS"%>
Namespace="CompCS"%>
<%@
<%@ Import
Import Namespace="CompVB"%>
Namespace="CompVB"%>
literal content.

! Specify Code Declaration Blocks

*ILLEGAL FOR NON-TRAINER USE**

An ASP.NET file is a text file that contains markup syntax for coding server-
side page logic, dynamic output, and literal content. By default, ASP.NET files
have an .aspx extension or .ascx for user controls. However, ASP.NET will
parse and compile any file that is mapped to the aspnet_isapi.dll under IIS.

Specifying @ Page Directives

To create the ASP.NET page that calls the string component, you first specify
page-specific attributes within a page directive. Page directives specify optional
settings that are used by the page compiler when processing ASP.NET files, as
shown in the following example:
<%@ Page Language="C#" Description="ASP.NET Client" %>

The following table describes the two @ Page directive attributes that are used
in the sample client ASP.NET page.
Attribute Description

Language Language that is used when compiling all <% %> and <%= %> blocks
within a page. Can be Visual Basic, C#, or Microsoft JScript® .NET.
Description Provides a text description of the page. Supports any string description.
30 Module 3: Working with Components

Specifying @ Import Directives

After specifying an @ Page directive, you include an @ Import directive,
which explicitly imports a namespace into a page, as in the following example:
<%@ Import Namespace="CompCS"%>
<%@ Import Namespace="CompVB"%>

When you use an @ Import directive to import a namespace into a page, all
classes and interfaces of the imported namespace are made available to the
page. The imported namespace can be part of the .NET Framework class library
or a user-defined namespace. In addition, the @ Import directive specifies the
name of the assembly that will be used. The assembly must be located in the
\Bin subdirectory of the application’s starting point.

Specifying Code Declaration Blocks

After specifying @ Page directives and importing the required namespaces, you
add code declaration blocks in which you place the code that calls the string
component in the ASP.NET page.
You define code declaration blocks by using <script> tags that contain a runat
attribute, which tells the server to execute the code on the server, instead of
sending the code text back to the client as part of the HTML stream. The script
element may optionally use a language attribute to specify the language of its
inner code, as in the following example:
<html>
...
<script language="C#" runat=server>
...
</script>
...
</html>

If you do not specify a language, ASP.NET defaults to the language that was
configured for the base page, which is determined by the @ Page directive.
For more information about directives in ASP.NET, see “Directive Syntax” in
the .NET Framework SDK documentation.
Module 3: Working with Components 31

Coding the Page_Load Event Handler

Topic Objective void
void Page_Load(Object
Page_Load(Object sender,
sender, EventArgs
EventArgs EvArgs)
EvArgs)
To explain how to code the {{
Page_Load event handler. StringBuilder
StringBuilder Out Out == new
new StringBuilder("");
StringBuilder("");
Lead-in int Count =
int Count = 0; 0;
The Page_Load event //
// Iterate
Iterate over
over component's
component's strings
strings and
and concatenate
concatenate
contains most of the code Out.Append("Strings
Out.Append("Strings from from C#
C# Component<br>");
Component<br>");
for the sample client CompCS.StringComponent
CompCS.StringComponent myCSStringComp
myCSStringComp == new
new
program. CompCS.StringComponent();
CompCS.StringComponent();
for(int
for(int index
index == 0;
0; index
index << myCSStringComp.Count;
myCSStringComp.Count;
index++)
index++)
{{
Out.Append(myCSStringComp.GetString(index));
Out.Append(myCSStringComp.GetString(index));
Out.Append("<br>");
Out.Append("<br>");
}}
//
// ……
Message.InnerHtml
Message.InnerHtml == Out.ToString();
Out.ToString();
}}

*ILLEGAL FOR NON-TRAINER USE**

The Page_Load event contains most of the code for the sample client program.
The following example shows the Page_Load event-handling code:
void Page_Load(Object sender, EventArgs EvArgs)
{
StringBuilder Out = new StringBuilder("");
int Count = 0;

// Iterate over component's strings and concatenate

Out.Append("Strings from C# Component<br>");
CompCS.StringComponent myCSStringComp = new
CompCS.StringComponent();

for(int index = 0; index < myCSStringComp.Count; index++)

{
Out.Append(myCSStringComp.GetString(index));
Out.Append("<br>");
}
Out.Append("<br>");

// Iterate over component's strings and concatenate

Out.Append("Strings from VB Component<br>");
CompVB.StringComponent myVBStringComp = new
CompVB.StringComponent();

for(int index = 0; index < myVBStringComp.Count; index++)

{
Out.Append(myVBStringComp.GetString(index));
Out.Append("<br>");
}
Message.InnerHtml = Out.ToString();
}
32 Module 3: Working with Components

Notice that the client code that calls the string component is very similar to the
code for the stand-alone console and Windows Forms-based applications. After
declaring the Page_Load event handler and initializing variables, you create a
new instance of the StringComponent class and iterate over the string array.
Each of the strings is appended to the variable Out. You then assign Out to a
property of an HTML server control, as in the following example:
Message.InnerHTML = Out.ToString();

Instead of assigning Out to a property of an HTML server control, you can use
Response.Write to write the stream directly into the HTML stream.

Note It is a recommended practice with ASP.NET forms to place the

executable code in a separate file from the declarative HTML. However, for the
sake of simplicity, the code for the ASP.NET page in this module has not been
placed in a separate file.
Module 3: Working with Components 33

Generating the HTML Response

Topic Objective
To show how to generate
the HTML response by
using the Message object. ! Specify the Body of the HTML Response
Lead-in
The following example <body>
<body>
shows how to create the <span
<span id="Message"
id="Message" runat=server/>
runat=server/>
HTML response by using </body>
the Message object. </body>

*ILLEGAL FOR NON-TRAINER USE**

The following example shows how to create the HTML response by using the
Message object:
<body>
<span id="Message" runat=server/>
</body>

This code places the string output that was generated by the Page_Load event
handler in the HTTP response.
34 Module 3: Working with Components

The code for the final ASP.NET page is as follows:

<%@ Page Language="C#" Description="ASP.NET Component Test" %>
<%@ Import Namespace="CompCS"%>
<%@ Import Namespace="CompVB"%>
<%@ Import Namespace="System.Text"%>

<html>
<script language="C#" runat=server>
void Page_Load(Object sender, EventArgs EvArgs) {
StringBuilder Out = new StringBuilder();
int Count = 0;

// Iterate over component's strings and concatenate

Out.Append("Strings from C# Component<br>");
CompCS.StringComponent myCSStringComp = new
CompCS.StringComponent();
for (int index = 0; index < myCSStringComp.Count; index++){
Out.Append(myCSStringComp.GetString(index));
Out.Append("<br>");
}
Out.Append("<br>");

// Iterate over component's strings and concatenate

Out.Append("Strings from VB Component<br>");
CompVB.StringComponent myVBStringComp = new
CompVB.StringComponent();
for (int index = 0; index < myVBStringComp.Count; index++){
Out.Append(myVBStringComp.GetString(index));
Out.Append("<br>");
}

Message.InnerHtml = Out.ToString();
}
</script>
<body>
<span id="Message" runat=server/>
</body>
</html>
Module 3: Working with Components 35

Demonstration: Testing the ASP.NET Client

Topic Objective
To demonstrate how to test
the ASP.NET page.
Lead-in
In this demonstration, you
will see how to test the
ASP.NET page.

*ILLEGAL FOR NON-TRAINER USE**

This demonstration shows how to test the ASP.NET page that was created in
For Your Information Creating an ASP.NET Client in this module. Before testing the page, you must
For instructions on running
this demonstration, see the
first configure a virtual directory that points to the directory that contains the
Instructor Notes. This exact .aspx file. You can use the New Directory Wizard in the IIS snap-in to do this.
procedure is repeated in
Lab 3.3, “Calling a
Component Through an
ASP.NET Page.”
36 Module 3: Working with Components

Lab 3.3: Calling a Component Through an ASP.NET Page

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will learn
how to create an ASP.NET
page that uses a previously
developed .NET Framework
component to create an
ASP.NET application.

*ILLEGAL FOR NON-TRAINER USE**

Objectives
After completing this lab, you will be able to create an ASP.NET page that uses
a previously developed .NET Framework component to create an ASP.NET
application.

Lab Setup
Starter and solution files are associated with this lab. The starter files are in the
folder <install folder>\Labs\Lab03.3\Starter, and the solution files are in the
folder <install folder>\Labs\Lab03.3\Solution.

Scenario
The labs associated with Module 3 are based on a small client/server
application scenario in which a .NET Framework component may be used in
several different client scenarios. The component may be written in any .NET
Framework runtime-compatible language, but you will only create a C#
component.
Lab 3.2, “Creating a Simple Console-Based Client,” and Lab 3.3, “Calling a
Component Through an ASP.NET Page,” demonstrate how the same
component code runs unchanged in different client environments.
This lab focuses on using an ASP.NET page to call the component and display
the results in a Web browser.

Estimated time to complete this lab: 30 minutes

Module 3: Working with Components 37

Exercise 1
Writing the ASP.NET Page
In this exercise, you will create an ASP.NET page that uses the same
StringComponent component that was used in the stand-alone client
application that you created in Lab 3.2, “Creating a Simple Console-Based
Client.” You will build a string object that holds the results of processing the
string array in the StringComponent class and generates output that can be
displayed in a Web browser.

! Create an ASP.NET page

1. Open Notepad and enter an @ Page directive that specifies the following
page attributes:
a. Language = C#
b. Description = “ASP.NET Component Test”
2. Import the following namespaces into the page:
a. CompCS
b. CompVB
c. System.Text
3. Create HTML script that specifies C# as the script language and uses the
runat=server directive.

! Call the StringComponent class

1. Create a handler for the Page_Load event and initialize a local variable
called Out of type StringBuilder to represent the string array in the
StringComponent class.
StringBuilder Out = new StringBuilder("");

2. Declare a local variable called Count of type int to obtain the number of
string elements in the string array.
3. Call the Append method on the Out variable with the following string that
has as it final characters an HTML line break, "<br>":
"Strings from C# Component<br> "
4. Assign to a local variable called myCSStringComp a new instance of the
C# version of the StringComponent class.
5. Iterate over all the strings of the C# string component. In each iteration,
append the component’s string to the string variable named Out and then
append an HTML line break, "<br>".
6. Append the string "<br>Strings from the VB Component<br>" to the Out
string and repeat steps 4 and 5 for the Visual Basic version of the
StringComponent class. The local variable name is myVBStringComp.
7. Assign the result of processing the string array to an HTML server control
so that the output is dynamically generated on a Web page. Use the
ToString method to get the output string from the Out variable.
8. Save the file as ClientASP.NET.aspx in the <install folder>\Labs\
Lab03.3\Starter\ASP.NET_Client folder.
38 Module 3: Working with Components

Exercise 2
Building and Testing the ASP.NET Page
In this exercise, you will configure a virtual directory to point to a directory
where the ASP.NET page is located, so that you can test the ASP.NET
application that is a client of the previously created string component.

! Configure a virtual directory

1. Click Start, Control Panel, Performance and Maintenance,
Administrative Tools, and then click Internet Information Services.
2. Expand the computer icon, expand the Web Sites folder, and then expand
and select Default Web Site.
3. Click the Action menu, point to New, and then click Virtual Directory.
The Virtual Directory Creation Wizard starts.
4. Click Next to continue.
5. In the Alias text box, type Test and click Next.
6. Browse to the <install folder>\Labs\Lab03.3\Starter\ASP.NET_Client
folder that contains the file ClientASP.NET.aspx that you created in
Exercise 1, click OK, and then click Next.
7. On the Access Permissions page, accept the default selections, click Next,
and then click Finish.
The Test folder is added to the Default Web Site.
Module 3: Working with Components 39

! Test the ASP.NET Client

1. Ensure that the compiled component DLLs, CompCS.dll and CompVB.dll,
are in a \Bin subdirectory under the starting point for the application virtual
directory.
2. Open Microsoft Internet Explorer, in the Address bar, type
http://localhost/Test/ClientASP.NET.aspx and then press ENTER.
A dialog box that generates the correct string output should appear, as
shown in the following illustration:
40 Module 3: Working with Components

Review
Topic Objective
To reinforce module
objectives by reviewing
key points. ! An Introduction to Key .NET Framework Development
Technologies
Lead-in
The review questions cover ! Creating a Simple .NET Framework Component
some of the key concepts
taught in the module. ! Creating a Simple Console Client
! Creating an ASP.NET Client

*ILLEGAL FOR NON-TRAINER USE**

1. How do .NET methods indicate failure?
All .NET Framework methods indicate failure by throwing exceptions.

2. What namespace contains the classes to create a Windows Form

application?
The Windows Forms library is located in the System.Windows.Forms
namespace.

3. What is the default extension for ASP.NET pages?

By default, ASP.NET files have an .aspx extension or .ascx for user
controls.
Module 4: Deployment
and Versioning

Contents

Overview 1
Introduction to Application Deployment 2
Application Deployment Scenarios 7
Related Topics and Tools 31
Lab 4: Packaging and Deployment 37
Review 42
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, place or event is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

 2001-2002 Microsoft Corporation. All rights reserved.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Module 4: Deployment and Versioning iii

Instructor Notes
Presentation: After completing this module, students will be able to:
90 Minutes
! Package and deploy simple and componentized applications.
Lab: ! Create strong-named assemblies.
50 Minutes
! Install and remove assemblies from the global assembly cache.
! Configure an application to control its binding to an assembly based on the
assembly’s location and version data.

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach
this module.

Required Materials
To teach this module, you need the Microsoft® PowerPoint® file 2349B_04.ppt.

Preparation Tasks
To prepare for this module, you should:
! Read all of the materials for this module.
! Complete the lab.
iv Module 4: Deployment and Versioning

Module Strategy
Use the following strategy to present this module:
! Introduction to Application Deployment
Introduce common concepts, such as the Microsoft .NET Framework
hierarchy of namespaces, the organization of assemblies, and the role of the
assembly manifest. Describe simple and componentized applications, and
their configuration and distribution scenarios.
! Application Deployment Scenarios
The examples in this section show how to deploy a simple stand-alone
application, an application that uses a shared assembly, and an application
that makes use of assembly versioning.
Introduce compapp, a componentized application, which uses multiple
assemblies. Contrast compapp with the simple single assembly Hello
World application that was created in Module 2, “Introduction to a
Managed Execution Environment,” in Course 2349B, Programming with
the Microsoft .NET Framework (Microsoft Visual C#™ .NET).
! Related Topics and Tools
Briefly introduce additional topics that are related to deployment and
versioning but are beyond the scope of this course. This section also
provides a list of tools that you can use to work with assemblies.
You should just inform the students of these topics and encourage them to
look for more information in the .NET Framework Software Development
Kit (SDK) documentation. In addition, Course 2350A, Securing and
Deploying Microsoft .NET Assemblies (Prerelease), covers code access
security and role-based security in greater detail.
Module 4: Deployment and Versioning 1

Overview
Topic Objective
To provide an overview of
the module topics and
objectives.
! Introduction to Application Deployment
Lead-in ! Application Deployment Scenarios
In this module, you will learn
about packaging and ! Related Topics and Tools
deployment of Microsoft
.NET Framework
applications and
assemblies.

*ILLEGAL FOR NON-TRAINER USE**

This module introduces the concepts of packaging and deployment of
Microsoft® .NET Framework applications and assemblies. The .NET
Framework provides improved isolation of application assemblies, simplified
application deployment, and robust versioning.
This module walks you through the packaging and deployment of a simple
Hello World application, and a small, componentized application. These
applications are written in C#, the new language designed for the .NET
Framework. The steps that are necessary to construct, compile, and run C#
applications were explained in Module 2, “Introduction to a Managed
Execution Environment,” and Module 3, “Working with Components,” both in
Course 2349B, Programming with the Microsoft .NET Framework (Microsoft
Visual C#™ .NET).
Because this course is an introduction to programming in the .NET Framework,
you should spend some time reading the .NET Framework Software
Development Kit (SDK) documentation. In fact, the labs, demonstrations, and
material for this module and other modules in this course are based on several
tutorials in the .NET Framework SDK.
After completing this module, you will be able to:
! Package and deploy simple and componentized applications.
! Create strong-named assemblies.
! Install and remove assemblies from the global assembly cache.
! Configure an application to control its binding to an assembly based on the
assembly’s location and version data.
2 Module 4: Deployment and Versioning

" Introduction to Application Deployment

Topic Objective
To introduce issues that
arise in application
deployment and to introduce ! Common Concepts
the topics in the section.
! Simple Applications
Lead-in
You can deploy a .NET ! Componentized Applications
Framework application in
several ways. ! Configuration and Distribution

*ILLEGAL FOR NON-TRAINER USE**

You can deploy a .NET Framework application in several ways depending on
the following considerations:
! The complexity of the application
! The sharing of assemblies with other applications
! The application’s security and protection requirements
! The application’s method of distribution

An application’s deployment is not affected by the .NET Framework common

language runtime-compatible language that is used to develop the application.
All applications that are written for use with the .NET Framework are compiled
to the same self-describing, Microsoft intermediate language (MSIL) code and
run with he same .NET Framework runtime.
This section introduces common concepts, such as the .NET Framework
hierarchy of namespaces, the organization of assemblies, and the role of the
assembly manifest. It then describes simple and componentized applications,
and their configuration and distribution.
Module 4: Deployment and Versioning 3

Common Concepts
Topic Objective
To review the organization
of the .NET Framework ! Classes and Types Used in .NET Framework Applications Are:
class library and # Organized in a hierarchy of namespaces
assemblies, and the role of
the assembly manifest. # Stored in PE files, such as DLLs and EXEs
Lead-in # Fully described by metadata
The .NET Framework
! Assemblies:
provides a common class
library that is organized into # Are made up of one or more PE files
a hierarchical tree of
namespaces. # Contain a manifest that identifies the assembly and its files
# Specify exported and imported classes and types
# Are units of deployment, reuse, and versioning

*ILLEGAL FOR NON-TRAINER USE**

As you learned in Module 2, “Introduction to a Managed Execution
Environment,” in Course 2349B, Programming with the Microsoft .NET
Framework (Microsoft Visual C# .NET), in addition to the common language
runtime, the .NET Framework provides a common class library that is
organized into a hierarchical tree of namespaces.
At the root of this hierarchy is the System namespace, which contains objects
for many other useful classes that can be used from any .NET-compatible
language. These objects include objects that are used for file I/O, messaging,
networking, and security.

For Your Information The Organization of PE Files into Assemblies

This topic reviews
The .NET Framework class library that you and others create are also organized
information that was
covered in Module 2. Do not
into hierarchical namespaces and stored in portable executable (PE) files, most
spend much time on this typically DLLs and EXEs. A single PE file can contain several namespaces,
topic. Present the material including nested namespaces. You also can split a namespace across multiple
as the starting point for a PE files. One or more PE files, and possibly non-PE files, such as resources, are
discussion of deployment combined to create an assembly, which is a physical unit that can be deployed,
and versioning. versioned, and reused.

The Role of the Assembly Manifest

In the .NET Framework, each class type is fully described through the type’s
metadata. Each assembly contains a manifest that includes the name of each
type that is exported from the assembly, along with information about the file
that contains that type’s metadata. The manifest also includes information about
the identity of the assembly, such as name, files that make up the assembly, and
version information, and full information about any dependencies on other
assemblies.
The .NET Framework runtime uses assembly manifests to locate and bind to
the referenced types.
4 Module 4: Deployment and Versioning

Simple Applications
Topic Objective
To describe how easily an
application can be executed
in the .NET Framework. ! Require .NET Runtime Be Installed on Local Computer
Lead-in ! Can Be Run Directly from a File Server or Copied
In the simplest case, a .NET Locally
Framework application can
be executed locally on any ! Make No Registry Entries
computer on which the .NET
runtime is already installed. ! Cannot Break Another Application
# Eliminate DLL Hell
! Can Be Uninstalled by Deleting Locally Copied File(s)

*ILLEGAL FOR NON-TRAINER USE**

In the simplest case, a .NET Framework application can be executed locally on
any computer on which the .NET runtime is already installed. The program can
run directly from a file server, or the files can be copied locally. Nothing else is
required. No registry entries are made, and no other applications are broken or
caused to stop running as a result.
The fact that no registry entries are made eliminates DLL versioning issues,
commonly referred to as “DLL hell.” Just deleting the executable file, if it was
copied locally, is sufficient to remove the application and leave no trace on the
computer.
Module 4: Deployment and Versioning 5

Componentized Applications
Topic Objective
To describe how assemblies
are handled in
componentized applications. ! Assemblies Private to an Application
Lead-in # Same as a simple application
Componentized applications
are only slightly more ! Assemblies Private to Related Applications
complex than applications.
# Deployed into a common subdirectory
! Assemblies Shared with Other Unrelated Applications
# Require a strong name and version information
# Deployed into the global assembly cache

*ILLEGAL FOR NON-TRAINER USE**

Componentized applications are only slightly more complex than simple
applications. The complexity of componentized applications depends on
whether their components are:
! Contained in assemblies that are private to the application.
! Shared with other related applications.
! Shared with other potentially unknown applications.

If all of the component assemblies are private, the componentized application

can be treated in the same manner as the application. The application can run
from a file server, or the application files can be copied to a local volume.
Deleting all of a componentized application’s files is sufficient to remove the
program.
Likewise, if several related applications use the same component assemblies,
those assemblies can be located in a common subdirectory. However, if the
application uses assemblies that are shared with other unrelated applications,
these assemblies can be installed in the global assembly cache and have certain
properties, such as a unique strong name that includes version information, that
enable the .NET runtime to ensure that the application binds to the appropriate
versions.
6 Module 4: Deployment and Versioning

Configuration and Distribution

Topic Objective
To introduce options for
configuring and deploying ! Configuration
applications in the .NET
Framework. # Maintained in plain-text files
Lead-in
As a developer of .NET ! Deployment
Framework applications,
# Common distribution formats, such as a .CAB file
you should be aware of the
different ways in which or a .MSI file
applications may be
# Common distribution mechanisms, such as
configured and packaged for
distribution.
Windows 2000 IntelliMirror or Microsoft Systems
Management Server

*ILLEGAL FOR NON-TRAINER USE**

As a developer of .NET Framework applications, you should be aware of the
different ways in which applications may be configured and packaged for
distribution. Usually, individual organizations, or an administrator within an
organization, decide how an application is packaged for distribution and
configured for the organization.

Configuration
In the .NET Framework, you can maintain application configuration in plain
text files. This use of plain text XML-based application configuration files
allows administrators to tailor an application’s behavior on a particular
computer without having to involve developers in the process.
The following section, Application Deployment Scenarios, presents several
common application scenarios. While this module does not cover ASP.NET
deployment, most of the concepts that are presented in this module apply to
ASP.NET deployment.

Deployment
Many client applications may be further packaged in a common distribution
format, such as a .CAB file or .MSI file. Client applications may also be
installed by using application distribution mechanisms, such as Microsoft
Windows® 2000 IntelliMirror® or Microsoft Systems Management Server
(SMS), which both use the Microsoft Windows Installer technology.
The Microsoft Windows Installer is an installation and configuration service
that is included in the Windows 2000 operating system. It is provided in a
service pack to Microsoft Windows 95, Microsoft Windows 98, and Microsoft
Windows NT® version 4.0.
For more information about the Microsoft Windows Installer, see the Platform
SDK documentation.
Module 4: Deployment and Versioning 7

" Application Deployment Scenarios

Topic Objective
To introduce the topics in
the section. ! A Simple Application
Lead-in ! A Componentized Application
This section shows how to
deploy a variety of ! Specifying a Path for Private Assemblies
applications, from simple ! A Strong-Named Assembly
applications to applications
that make use of assembly ! Deploying Shared Components
versioning. ! A Versioned Assembly
! Creating Multiple Versions of a Strong-Named Assembly
! Binding Policy
! Deploying Multiple Versions of a Strong-Named Assembly

*ILLEGAL FOR NON-TRAINER USE**

The examples in this section show how to deploy a simple application, an
application that uses a shared assembly, and an application that makes use of
assembly versioning.
8 Module 4: Deployment and Versioning

A Simple Application
Topic Objective
To explain how a simple ! Use the Microsoft Intermediate Language Disassembler
application is deployed. (Ildasm.exe) to Examine the Assembly Manifest
Lead-in
In Module 2, you looked at # Version information
the simplest .NET
Framework application, the
# Imported types
traditional Hello World # Exported types
application written in C#.
! Deploy the Application by:
# Running the executable file directly from a file server, or
# Installing it locally by copying the file
# Uninstall the application by deleting the file

*ILLEGAL FOR NON-TRAINER USE**

In Module 2, “Introduction to a Managed Execution Environment,” in Course
For Your Information 2349B, Programming with the Microsoft .NET Framework (Microsoft
Point out that while Hello
World is simplistic, it is
Visual C# .NET), you looked at the simplest .NET Framework application, the
extremely versatile in its traditional Hello World application written in C#. The C# source code for that
ability to easily demonstrate program, HelloDemoCS, is as follows:
many new concepts of the
using System;
.NET Framework, including
deployment and versioning.
class MainApp {
public static void Main() {
Console.WriteLine("Hello World using C#!");
}
}

This simple executable file prints a single line to the System.Console, a type
that is contained in the .NET Framework class library. It does not reference any
other libraries and does not itself produce a library.
Module 4: Deployment and Versioning 9

Using Microsoft Intermediate Language Disassembler to

Examine Hello World
Compiling this small application generates the HelloDemoCS.exe.

Important To use Microsoft Visual Studio® .NET tools within a command

If you run the Microsoft intermediate language (MSIL) disassembler

(Ildasm.exe) against this executable file, a window appears, similar to the
following illustration.

The simple Hello World application highlights a particularly important concept

behind programming for the .NET Framework. The application is clearly self-
describing: all of the information that is needed to understand the application is
contained in the metadata.
The MSIL disassembler shows the classes or types that are created within the
application. In the case of the Hello World application, the only class is
MainApp. The MSIL disassembler also shows the methods Main and a default
constructor, indicated by .ctor. The program does not have any other members.
To save information about the assembly to a file, use the Dump command on
the File menu.
10 Module 4: Deployment and Versioning

To see additional information about the application, double-click Manifest. The

following window appears.

The preceding illustration shows the manifest, which contains information

about the assembly, including the version (not yet set), external libraries, and
types within those libraries, which the application uses.

Deployment
Deployment to computers on which the .NET runtime is installed is a simple
process. The Hello World application can run directly from a file server. More
advanced programs may involve security issues.
In the simple Hello World case, no files are placed on the workstation, no
entries are made in the system registry, and, in effect, there is no affect on the
client workstation. There is also nothing to clean up because there is nothing to
remove on the client workstation.
As you would expect, HelloDemoCS.exe can also be copied to a local volume.
In this scenario, you can remove the program by deleting the file, and as before,
nothing would remain on the workstation.
Whether you run HelloDemoCS.exe from a file server or copy it to a local
volume, running this application will not break another program, and no other
application can cause HelloDemoCS.exe to stop functioning.
Module 4: Deployment and Versioning 11

A Componentized Application
Topic Objective
To introduce compapp, a
componentized application,
which uses multiple ! Assembly Component to Be Used by Application
assemblies.
# Assembly Stringer.dll is built from Stringer.cs as follows:
Lead-in
The Hello World application csc
csc /target:library
/target:library Stringer.cs
Stringer.cs
that is discussed in the
preceding topic is ! Client Needs to Reference Assembly
completely trivial and hardly
representative of even the csc
csc /reference:Stringer.dll
/reference:Stringer.dll Client.cs
Client.cs
simplest real-world
application.
! Deployment by File Server or Local Copy

*ILLEGAL FOR NON-TRAINER USE**

The Hello World application that is discussed in the preceding topic is
completely trivial and hardly representative of even the simplest real-world
application. This topic covers compapp, a componentized application, which
uses multiple assemblies.
12 Module 4: Deployment and Versioning

Creating Stringer.dll
The client, Client.exe, calls types that are contained in a component assembly
that is named Stringer (Stringer.dll). The source code for the Stringer
assembly, is located in Stringer.cs:
using System;

namespace org {
public class Stringer {
private string[] StringSet;

public Stringer() {
StringSet = new string[] {
"C# String 0",
"C# String 1",
"C# String 2",
"C# String 3"
};
}

public string GetString(int index) {

if ((index < 0) || (index >= StringSet.Length)) {
throw new IndexOutOfRangeException();
}
return StringSet[index];
}

public int Count {

get { return StringSet.Length; }
}
}
}
Module 4: Deployment and Versioning 13

A client application that uses this component could fully qualify a reference to
the Stringer class, for instance, as org.Stringer. Alternatively, a client
application could include a using statement to allow easy access to the types in
Stringer.dll by specifying the namespace, as shown in the Client.cs source code:
using System;
using org;

class MainApp {
public static void Main() {
Stringer myStringComp = new Stringer();
string[] StringsSet = new string[4];
// Iterate over component's strings
Console.WriteLine("Strings from StringComponent");
for (int index = 0; index < myStringComp.Count; index++)
{
StringsSet[index] = myStringComp.GetString(index);
Console.WriteLine(StringsSet[index]);
}
// ...
}
}

Building the Application

To build this componentized application, you first build the Stringer.dll
assembly component. Then, you build Client.exe, importing the Stringer
component by using the name of the file that contains the manifest, Stringer.dll,
rather than the namespace name, which is org in this case.
csc /target:library Stringer.cs
csc /reference:Stringer.dll Client.cs

The MSIL disassembler displays the Stringer.dll and shows all of the members,
as in the following illustration.
14 Module 4: Deployment and Versioning

Like HelloDemoCS.exe, Client.exe contains manifest information about itself,

the System library, and the types that the application uses. However, the
manifest now contains information about the Stringer assembly.
A MSIL disassembler display of the manifest for Client.exe shows the reference
to the Stringer assembly, as in the following illustration.

Deployment
Like the simple application, Client.exe can run directly from a file server on any
workstation that has the .NET runtime installed. Client.exe and Stringer.dll can
also be copied to a local volume. To remove the application, you need only
delete the two files.
Module 4: Deployment and Versioning 15

Specifying a Path for Private Assemblies

Topic Objective
To show how to use a ! Specifying a Directory From Which to Load Private
configuration file to specify a Assemblies.
path for private assemblies.
# Client.exe.config file specifies a privatePath tag
Lead-in <configuration>
The .NET Framework <configuration>
provides a configuration <runtime>
<runtime>
mechanism that allows <assemblyBinding
<assemblyBinding
administrators to specify a xmlns="urn:schemas-microsoft-com:asm.v1">
xmlns="urn:schemas-microsoft-com:asm.v1">
directory from which to load
<probing
<probing privatePath=“MyStringer"/>
privatePath=“MyStringer"/>
private assemblies.
</assemblyBinding>
</assemblyBinding>
</runtime>
</runtime>
</configuration>
</configuration>
! Configuration File’s XML Tags Are Case-Sensitive

*ILLEGAL FOR NON-TRAINER USE**

The preceding Client.exe example has one important weakness: both Client.exe
and Stringer.dll reside in the same directory. In the real world, an administrator
may wish to use a directory structure to manage assemblies. The .NET
Framework provides a configuration mechanism that allows administrators to
specify a directory from which to load private assemblies.

Locating Stringer.dll and Client.exe in Separate

Directories
Using the preceding Client example, all of the source code is the same, but for
illustration purposes the build process has been modified so that the component
application’s Stringer.dll is built in its own subdirectory named MyStringer.
cd \compapp
csc /target:library /out:MyStringer\Stringer.dll!
MyStringer\Stringer.cs
csc /reference:MyStringer\Stringer.dll Client.cs

Using a Configuration File to Locate Assemblies at Run

Time
Although the /reference: compile option locates an assembly in a directory
when compiling the program, a separate XML-based application configuration
file is required at run time to support assemblies that are located in other
directories. For client executable files like the examples that are covered in this
module, the configuration file resides in the same directory as the executable
file. The configuration file has the complete name of the executable file with an
additional extension of .config.
16 Module 4: Deployment and Versioning

The Client.exe configuration file is called Client.exe.config. It specifies a

privatePath attribute, as shown in the following example:
<configuration>
<runtime>
<assemblyBinding
xmlns="urn:schemas-microsoft-com:asm.v1">
<probing privatePath="MyStringer"/>
</assemblyBinding>
</runtime>
</configuration>

Important The configuration file’s XML tags are case-sensitive.

When this configuration file is placed in the same directory as the executable
file, at run time, the .NET Framework uses the privatePath attribute to
determine where to look for components—in addition to looking in the
application directory.

Note When loading an assembly, the runtime also searches for a private path
that is equal to the name of the assembly. If the Stringer.dll assembly was
located in a subdirectory named Stringer, instead of MyStringer, then a
configuration file would be unnecessary.

Deployment
Like the simple application, the revised Client.exe can run directly from a file
server on any workstation that has the .NET runtime installed. Client.exe,
Stringer.dll, and the application’s .config file can also be copied to a local
volume, using the same relative directory structure. Deleting the files and
directory effectively removes the application.
While they are not used in the preceding example, it is important to know that
in addition to application configuration files, the .NET Framework also
supports separate user and Computer Configuration Files for many common
configuration settings.
Module 4: Deployment and Versioning 17

A Strong-Named Assembly
Topic Objective
To discuss the problems ! Global Assembly Cache
that may occur when # Contains assemblies shared by unrelated applications
multiple applications share
components, and to ! Strong Names Are Required for Assemblies in the Cache
introduce the use of strong # Generate a public-private key pair:
names.
sn
sn –k
–k orgKey.snk
orgKey.snk
Lead-in
The client applications # Add code to source file to specify version and key information:
discussed in the preceding
topics are limited in that they #if
#if STRONG
STRONG
only illustrate the use of [assembly:
[assembly: System.Reflection.AssemblyVersion("1.0.0.0")]
System.Reflection.AssemblyVersion("1.0.0.0")]
assemblies that are private [assembly:
[assembly: System.Reflection.AssemblyKeyFile("orgKey.snk")]
System.Reflection.AssemblyKeyFile("orgKey.snk")]
#endif
#endif
to the Client.exe and do not
demonstrate the use of # Compile:
assemblies that are shared
csc
csc /define:STRONG
/define:STRONG /target:library
/target:library /out:AReverser.dll!
/out:AReverser.dll!
by more than one AReverser.cs
application. AReverser.cs
*****************************ILLEGAL FOR NON-TRAINER USE******************************
The client applications discussed in the preceding topics show the basics for
constructing a complex program, but they are limited in that they only illustrate
the use of assemblies that are private to the Client.exe and do not demonstrate
the use of assemblies that are shared by more than one application.
This topic discusses the problems that may occur when multiple applications
share components. It then introduces the use of strong names, the .NET
Framework solution to these problems.

Issues with Sharing Components

Many applications use assemblies that are shared by more than one application.
These shared assemblies, which are typically provided by third-party
developers, are installed in a common location on the system, the global
assembly cache. By default, the system looks for each application’s assemblies
in the global assembly cache.
In classic COM and COM+ applications, the sharing mechanism depends
heavily on the Windows System Registry in which information about each
component, including its version and physical file location, is stored. This
mechanism allows multiple applications to share a single component, but it also
allows a component of a newly installed application to replace an existing
component and possibly cause other applications to break.
Such overwriting of existing components is often difficult to detect because the
application that is causing the problem appears to work properly.
18 Module 4: Deployment and Versioning

Strong Names
In the .NET Framework, you can solve the problems that are caused by the
sharing of components with multiple applications by more strongly associating
a distinct build of a component assembly with the client application. A distinct
build is indicated by a combination of a version number and a special value that
is called the publicKeyToken.

Important Strong names provide a strong integrity check. Passing the .NET
Framework security checks guarantees that the contents of the assembly have
not been changed since it was built. Note, however, that strong names in and of
themselves do not imply a level of trust, such as that provided by a digital
signature and supporting certificate.

When component assemblies are associated with a distinct build, the system can
isolate these component assemblies, thus allowing different versions to run at
the same time for different client applications. This system of protection is
sometimes called side-by-side execution. It differs from backward compatibility
because with side-by-side execution, applications can run alongside other
versions of the same applications without affecting their respective execution
environments.
You can facilitate side-by-side execution by assigning strong names to your
assemblies. A strong name consists of the assembly’s identity, which includes
its simple text name, version number, and culture information, if provided, and
a public key.
To demonstrate these additional build attributes the client and component
scenario is extended by adding an assembly named AReverser. This assembly
contains a class with a method that is named Invert, which uses the
System.Array.Reverse method to reverse an array of strings.

Note The code details of AReverser are not relevant to deployment issues and
therefore are not shown. This module’s lab contains the complete code details.

Building the Assembly Without a Strong Name

You begin by building the new component assembly without specifying any
options to make it have a strong name. First, you compile the new AReverser
assembly, as follows:
csc /target:library /out:AReverser.dll AReverser.cs

After compiling the new AReverser assembly, you can examine the metadata
by using the MSIL disassembler. The MSIL disassembler indicates that the
assembly does not have an established version number, as shown in the
following code:
.assembly AReverser
{ ...
.hash algorithm 0x00008004
.ver 0:0:0:0
}
.module AReverser.dll
Module 4: Deployment and Versioning 19

Generating a Public-Private Key Pair

To create an assembly with a strong name, you must compile the assembly by
using a private key. Public keys are used for verification. Therefore, before
compiling the assembly, you must first generate a public-private key pair. You
use the Strong Name tool (Sn.exe) to generate a new key pair and place them in
a file, as in the following example:
sn –k orgKey.snk

Compiling a Strong-Named Assembly

Now that you have a private key, you are ready to compile the component,
specifying the key file and the version number to be assigned. You can do this
by specifying AssemblyVersion and AssemblyKeyFile attributes in the
AReverser.cs file using the STRONG conditional compilation symbol:
#if STRONG
[assembly: System.Reflection.AssemblyVersion("1.0.0.0")]
[assembly: System.Reflection.AssemblyKeyFile("orgKey.snk")]
#endif

You must then define STRONG in the compile process:

csc /define:STRONG /target:library /out:AReverser.dll!
AReverser.cs

If you run the MSIL disassembler again on AReverser.dll, you can verify that
the assembly is now strong-named from the presence of a .publickey property
and a non-default version, which is specified by the .ver property of 1:0:0:0.
The following example shows the disassembled code:
.assembly AReverser
{
...
.publickey = (00 ... 71 8A 7D 6A D7 )
.hash algorithm 0x00008004
.ver 1:0:0:0
}
.module AReverser.dll

For more information about the Strong Name tool, see Packaging and
Deployment Tools in this module.
20 Module 4: Deployment and Versioning

Deploying Shared Components

Topic Objective
To explain the commands ! Installing the Strong-Named Component in the Global
that are used to install, Assembly Cache
examine, and remove
assemblies from the global gacutil
gacutil /i
/i AReverser.dll
AReverser.dll
assembly cache.
Lead-in
While components can ! Examining the Global Assembly Cache
easily be shared by related
applications by putting them gacutil
gacutil /l
/l
in a common subdirectory,
shared assemblies that are
used by many applications ! Removing a Shared Component File
on the system are often
stored in the system’s global
gacutil
gacutil /u
/u AReverser
AReverser
assembly cache.

*ILLEGAL FOR NON-TRAINER USE**

Deployment with strong-named assemblies is usually more complicated than
deployment with assemblies that are not strong-named. While components can
easily be shared by related applications by putting them in a common
subdirectory, shared assemblies that are used by many applications on the
system are often stored in the system’s global assembly cache.
As with the previous examples of componentized applications, this revised
Client.exe can run directly from a file server on any workstation on which the
.NET runtime is installed. The Client.exe and Stringer.dll files can also be
copied to a local volume.

Installing a Strong-Named Assembly into the Global

Assembly Cache
Installing the strong-named component into the global assembly cache requires
the following additional command on the computer that will be running the
corresponding Client.exe program:
gacutil /i AReverser.dll

Note You must have Administrator privileges on a computer to install

assemblies into the global assembly cache. Assemblies that are installed in the
global assembly cache must have a strong name.

After installing the AReverser assembly, you can then examine the system
assembly cache by typing:
gacutil /l
Module 4: Deployment and Versioning 21

The output of this command is:

...
AReverser, Version=1.0.0.0, Culture=neutral, PublicKeyToken=!
0588613cb04b772e, Custom=null
...

You can also examine the system assembly cache by navigating to the
\WindowsDirectory\Assembly directory and by using the cache shell extension.

Uninstalling a Strong-Named Assembly from the System

Cache
Cleaning up applications that use strong-named assemblies requires more work
than cleaning up the simple applications or componentized applications that are
described in the preceding topics. In addition to deleting the executable files,
you should remove the shared component file from the global assembly cache
since the global assembly cache is not automatically scavenged.
To remove a shared component file, an administrator can use the cache shell
extension, select the appropriate components, and delete them. Developers and
administrators who want to automate the process, however, should use the
command-line interface to the assembly cache manager as follows:
gacutil /u AReverser

To confirm the removal, you can view the contents of the global assembly
cache by using the following command:
gacutil /l

For more information about installing and uninstalling shared assemblies to the
global assembly cache, see Packaging and Deployment Tools in this module.
22 Module 4: Deployment and Versioning

A Versioned Assembly
Topic Objective
To discuss the physical
representation and logical
mapping of the compatibility ! Applications Need to Bind to a Suitable Version of a
version number. Shared Assembly
Lead-in ! The Version Number Is Represented by a 4-Part Number
The final packaging and
deployment example in this
module involves updating <major
<major version>.<minor
version>.<minor version>.<revision>.<build
version>.<revision>.<build number>
number>
the shared assembly to a
new version.
! Applications Get the Versions of Assemblies with Which
They Were Built and Tested
# Unless overridden by explicit policy rules

*ILLEGAL FOR NON-TRAINER USE**

The final packaging and deployment example in this module involves updating
the shared assembly to a new version. In Creating Multiple Versions of a
Strong-Named Assembly in this module, the shared assembly is updated to
deliberately break compatibility with the client and to demonstrate how the
.NET Framework allows you to configure the client application to bind to the
desired version of the shared assembly.

Versioning
Each assembly has a specific compatibility version number as part of its
identity. As such, two assemblies that differ by compatibility version are
completely different assemblies as far as the .NET runtime class loader is
concerned.
This compatibility version number is physically represented as a four-part
number with the following format:
<major version>.<minor version>.<revision>.<build number>
Module 4: Deployment and Versioning 23

Each segment of this number has a specific meaning to the .NET runtime as it
decides which version of an assembly to load. Logically, the compatibility
version number has three parts, with the following meanings:
1. Incompatible
A change has been made to the assembly that is known to be incompatible
with previous versions.
Example: Major new release of the product
2. Maybe Compatible
A change has been made to the assembly that is thought to be compatible
and carries less risk than an incompatible change. However, backward
compatibility is not guaranteed.
Example: Service Pack or release of a new daily build
3. Quick Fix Engineering (QFE)
An engineering fix that customers may want to upgrade to.
Example: An emergency security fix

These three logical parts correspond to the physical four-part version number as
follows:

For example, an assembly with compatibility version number 2.0.0.0 is

considered incompatible with an assembly whose compatibility number is
1.0.0.0. Compatibility number 2.0.2.11 is considered a QFE to compatibility
number 2.0.2.1.
24 Module 4: Deployment and Versioning

Creating Multiple Versions of a Strong-Named Assembly

Topic Objective ! Building Two New Versions of AReverser with a New Key Pair
To explain how to create # Specify version 2.0.0.0 for one and 2.0.1.0 for the other
multiple versions of a For AReverser_v2.0.0.0\AReverser.cs:
shared component by using #if
strong-named assemblies. #if STRONG
STRONG
[assembly:
[assembly: System.Reflection.AssemblyVersion("2.0.0.0")]
System.Reflection.AssemblyVersion("2.0.0.0")]
[assembly:
[assembly: System.Reflection.AssemblyKeyFile("orgVerKey.snk")]
Lead-in #endif
System.Reflection.AssemblyKeyFile("orgVerKey.snk")]
#endif
In the .NET Framework, you
can solve the problems that ! Build
are inherent in working with csc
csc /define:STRONG
/define:STRONG /target:library!
/target:library!
multiple versions of a /out:AReverser_v2.0.0.0\AReverser.dll!
/out:AReverser_v2.0.0.0\AReverser.dll!
AReverser_v2.0.0.0\AReverser.cs
shared component by using AReverser_v2.0.0.0\AReverser.cs
strong-named assemblies. ! Use Ildasm.exe to Examine Different Versions
# Note the publickey and version numbers
.assembly
.assembly AReverser
AReverser
{{ ...
...
.publickey
.publickey == (00
(00 24
24 ...
... 82
82 B1
B1 F2
F2 A0
A0 ))
.hash
.hash algorithm
algorithm 0x00008004
0x00008004
.ver
.ver 2:0:1:0
2:0:1:0
*****************************ILLEGAL FOR NON-TRAINER USE******************************
In the .NET Framework, you can solve the problems that are inherent in
working with multiple versions of a shared component by using strong-named
assemblies. This topic examines how multiple versions of an assembly are
created.
Building on the code in the preceding strong-named AReverser assembly, two
separate versions of the strong-named component are created, and additional
application configuration options are used to show how an application can be
made to run. A method in version 2.0.1.0 of AReverser.dll is deliberately made
incompatible with the same method in version 2.0.0.0 so that a client that
successfully calls the method that is using version 2.0.0.0 will fail with the later
revision.
Versioning keys can change from one version of an assembly to the next. To
illustrate this, you generate a new key pair using the Strong Name (Sn.exe) tool
and place that new key pair in a file, as follows:
sn –k orgVerKey.snk

After creating a new private key, you add the following to the AReverser.cs file
in the AReverser_v2.0.0.0 subdirectory:
#if STRONG
[assembly: System.Reflection.AssemblyVersion("2.0.0.0")]
[assembly: System.Reflection.AssemblyKeyFile("orgVerKey.snk")]
#endif
Module 4: Deployment and Versioning 25

You add the following to the AReverser.cs file in the AReverser_v2.0.1.0

subdirectory:
#if STRONG
[assembly: System.Reflection.AssemblyVersion("2.0.1.0")]
[assembly: System.Reflection.AssemblyKeyFile("orgVerKey.snk")]
#endif

You compile both of these versions by using the commands:

csc /define:STRONG /target:library!
/out:AReverser_v2.0.0.0\AReverser.dll!
AReverser_v2.0.0.0\AReverser.cs
csc /define:STRONG /target:library!
/out:AReverser_v2.0.1.0\AReverser.dll!
AReverser_v2.0.1.0\AReverser.cs

If you run the MSIL disassembler on these two updated files, you can verify
that the assemblies are strong-named as indicated by the version number,
2.0.0.0 or 2.0.1.0, depending on which one you inspect with the MSIL
disassembler.
Notice that these two assemblies have the same publickey property, but the
value of this property is different than the previous version 1.0.0.0
AReverser.dll. This property is different because a different key pair was used,
orgVerKey.snk, instead of orgKey.snk.
The following example shows the MSIL disassembler output for version 2.0.1.0
of the AReverser.dll:
.assembly AReverser
{
...
.publickey = (00 24 ... 82 B1 F2 A0 )
.hash algorithm 0x00008004
.ver 2:0:1:0
}
26 Module 4: Deployment and Versioning

Binding Policy
Topic Objective ! Policy Resolution
To discuss binding policy. # Allows an assembly reference, specified at compile time, to be
modified after the application has been deployed without recompiling
Lead-in
Whenever the .NET ! Happens in the Following Stages:
Framework is asked to bind 1. Application-policy resolution
to a specific version of a
shared assembly, the 2. Publisher-policy resolution
version of the assembly 3. Administrator-policy resolution
reference may be altered at
! In Each Stage, an XML Configuration File Is Read
several policy-resolution
stages before the .NET # Note: XML is case-sensitive
Framework finally decides to ! Version Numbers of Assemblies That Are Not Strong-Named Are
which version to bind. Not Checked
! Configuration File Tag Examples
# privatePath
# bindingRedirect

*ILLEGAL FOR NON-TRAINER USE**

When the .NET Framework is asked to bind to a specific version of a shared
assembly, the version of the assembly reference may be altered at several
policy-resolution stages before the .NET Framework finally decides which
version to bind to. This policy-resolution process allows an assembly reference,
which is specified at compile time, to be modified after the application has been
deployed, without recompiling the assemblies involved.
Policy resolution happens in the following three stages:
1. Application-policy resolution
2. Publisher-policy resolution
3. Administrator-policy resolution

In each stage, an XML configuration file that describes the policy is read. The
privatePath attribute in the application-configuration file illustrates the simplest
form of application-policy resolution. In addition, the bindingRedirect tag can
be used to redirect the reference to a different version of a shared assembly.

Note The version numbers of assemblies that are not strong-named are not
checked.
Module 4: Deployment and Versioning 27

Publisher-policy resolution allows shared-component vendors to make

compatibility statements among different revisions of their software. These per-
assembly configuration files are distributed as strong-named assemblies and are
installed into the global assembly cache as part of a service pack-style update.
Any binding redirects that are specified by the publisher-policy file are then
applied to the reference, which is then subject to administrator-policy
resolution. Because publisher-policy assemblies affect all applications on the
system, it is important that these assemblies are installed separately from the
application.
Administrator-policy resolution is the final—and the strongest—stage in the
binding policy-resolution process. The administrator-policy file is located in the
WindowsDirectory\Microsoft.NET\Framework\v1.0.FinalBuildNumber\
CONFIG directory and is called Machine.config. This file has the same XML-
based schema as the policy files that are used in the two previous stages of
policy resolution. Administrator policy affects all assembly bindings that occur
on the system and can never be bypassed.
28 Module 4: Deployment and Versioning

Deploying Multiple Versions of a Strong-Named Assembly

Topic Objective
To explain how to deploy
multiple versions of a ! Install Both Versions of AReverser.dll into the Global Assembly
strong-named assembly. Cache

Lead-in gacutil
gacutil /i
/i AReverser_v2.0.0.0\AReverser.dll
AReverser_v2.0.0.0\AReverser.dll
After you have configured gacutil
gacutil /i AReverser_v2.0.1.0\AReverser.dll
/i AReverser_v2.0.1.0\AReverser.dll
both versions of the
AReverser assembly to use ! Compile the VerClient Executable and Specify Version 2.0.0.0 of the
strong names, you can AReverser Component
deploy those versions.
csc
csc /reference:MyStringer\Stringer.dll!
/reference:MyStringer\Stringer.dll!
/reference:AReverser_v2.0.0.0\AReverser.dll
/reference:AReverser_v2.0.0.0\AReverser.dll VerClient.cs
VerClient.cs

! Use Version Policies to Control Assembly Binding at Run Time

*ILLEGAL FOR NON-TRAINER USE**

After you have configured both versions of the AReverser assembly to use
strong names, you can deploy those versions.
To configure client applications to use strong-named assemblies of a specific
version, you must first install both 2.0 versions of AReverser.dll into the global
assembly cache as follows:
gacutil /i AReverser_v2.0.0.0\AReverser.dll
gacutil /i AReverser_v2.0.1.0\AReverser.dll

After installing these AReverser assemblies, you can then examine the global
assembly cache by using:
gacutil /l

You can also examine the system assembly cache by navigating to the
\WindowsDirectory\Assembly directory, and using the cache shell extension.
You now compile the VerClient executable file, for which you specify the
version 2.0.0.0 of the AReverser component, as shown in the following
example:
csc /reference:MyStringer\Stringer.dll!
/reference:AReverser_v2.0.0.0\AReverser.dll VerClient.cs
Module 4: Deployment and Versioning 29

Version Policies
All versioning of assemblies that use the common language runtime takes place
at the assembly level. The specific version of an assembly and the versions of
dependent assemblies are recorded in the assembly’s manifest. The rules that
specify the acceptable versions of an assembly are called version policies.
Version policies are expressed in configuration files.

Using Configuration Files to Override Version Policy

According to the default version policy for the runtime, applications run only
with the versions that they were built and tested with unless these versions were
overridden by explicit version policy in configuration files. These configuration
files, which include the application configuration file, a publisher policy file,
and the machine’s administrator configuration file, provide the means for
overriding the version policy that is recorded in the assembly manifest.

Binding to a Specific Assembly Version

In a configuration file, you can specify a version policy that instructs the
runtime to bind to a specific version of an assembly that you want the
application to use. This specific version policy allows you to bind to a different
version of an assembly than the version that is recorded in the assembly
manifest of the calling assembly. In particular, the bindingRedirect tag can be
used to redirect the reference to a different version of a shared assembly, by
overriding the version in the original reference with this newer version.
The following option says that for any assembly reference from version 2.0.0.0
through 2.0.0.9, the version that should instead be used at run time is 2.0.1.0:
<bindingRedirect
oldVersion="2.0.0.0-2.0.0.9" newVersion="2.0.1.0"
/>

This option allows an administrator to reconfigure an application without

having to have it recompiled.
30 Module 4: Deployment and Versioning

The following sample VerClient.exe.config file instructs the runtime to look in

subdirectory MyStringer for assembly references and to bind to version 2.0.0.0
of AReverser:
<configuration>
<runtime>
<assemblyBinding
xmlns="urn:schemas-microsoft-com:asm.v1">
<probing privatePath="MyStringer"/>
<publisherPolicy apply="no"/>
<dependentAssembly>
<assemblyIdentity name="AReverser"
publicKeyToken="52398B7804D8A95C"
culture=""/>
<publisherPolicy apply="no"/>
<bindingRedirect oldVersion="2.0.0.0"
newVersion="2.0.0.0"/>
</dependentAssembly>
</assemblyBinding>
</runtime>
</configuration>

Note The publicKeyToken tag’s value can be obtained using the Sn.exe tool or
by examining the global assembly cache by using gacutil /l or the cache shell
extension.

Important The Sn.exe switches to obtain the publicKeyToken do not work

correctly in some of the earlier .NET Framework versions, such as build 9188.

Because a method of a type in version 2.0.1.0 of AReverser.dll was deliberately

Key Points made incompatible with the same method in version 2.0.0.0, a version 2.0.0.0-
Reinforce the fact that the
configuration file’s XML tags
compatible client that attempted to call this later revision would fail. If
are case-sensitive. VerClient.exe.config changed the line:
newVersion="2.0.0.0"/>

to:
newVersion="2.0.1.0"/>

The resulting error message would be similar to:

Unhandled Exception: System.MissingMethodException:!
Method not found: at MainApp.Main()

More typically, the configuration file mechanism allows an administrator to

repair an application so that it will continue to run even if it is broken by a
subsequent install of another application that used a different version of the
same shared component.
Finally, when you need to clean up the application, remove the shared
component files from the global assembly cache, as shown in the following
example:
gacutil /u AReverser
Module 4: Deployment and Versioning 31

" Related Topics and Tools

Topic Objective
To introduce the topics in
the section.
! Related Topics
Lead-in
This section briefly ! Packaging and Deployment Tools
introduces additional topics
that are related to
deployment and versioning.

*ILLEGAL FOR NON-TRAINER USE**

This section briefly introduces additional topics that are related to deployment
and versioning, but are beyond the scope of this course. This section also
provides a list of tools that you can use to work with assemblies.
32 Module 4: Deployment and Versioning

Related Topics
Topic Objective
To briefly introduce several
related topics and provide
references for students to ! ASP.NET
follow up on.
! Assemblies
Lead-in
This module introduces the ! Security
concepts of packaging and
deployment of .NET ! Localization
Framework applications and
assemblies. Several related
topics are worth mentioning,
and, when appropriate,
references to additional
information are provided.

*ILLEGAL FOR NON-TRAINER USE**

This module introduces the concepts of packaging and deployment of .NET
Framework applications and assemblies. Several related topics are worth
mentioning, and, when appropriate, references to additional information are
provided.

For Your Information ASP.NET

Do not spend much time on
This module focuses on packaging and deploying traditional client applications.
this topic. The subject
matter is mostly beyond the
For more information about deploying ASP.NET applications to a Web server,
scope of the course. You see the .NET Framework SDK documentation.
should just inform the
students of these topics and Assemblies
encourage them to look for
more information in the
For more information about how the .NET Framework locates assemblies when
provided references. they are referenced at run time, see “How the Runtime Locates Assemblies” in
the .NET Framework SDK documentation. This topic covers the Assembly
Resolver, strong-named assemblies, application and administrator version
policies, codebase locations, and QFE updates.

Security
The.NET Framework offers code access security and role-based security to
address mobile code security concerns and to provide support that enables
components to determine what users are authorized to do. These security
mechanisms use a simple, consistent model so that developers who are familiar
with code access security can easily use role-based security and developers who
are familiar with role-based security can easily use code access security. Code
access security and role-based security are implemented by using a common
infrastructure that is supplied by the common language runtime.
Module 4: Deployment and Versioning 33

Code Access Security and Role-based Security

Code access security uses permissions to control the access that code has to
protected resources and operations. It helps to protect computer systems from
malicious mobile code and provides a way to allow mobile code to run safely.
Role-based security provides information that is needed to make decisions
about what a user is allowed to do. These decisions can be based on the user’s
identity, role membership, or both.
A more detailed discussion of security is outside the scope of this course. For
more information about security, see “Securing Your Application” in the .NET
Framework SDK documentation.
Additionally, Course 2350A, Securing and Deploying Microsoft .NET
Assemblies (Prerelease) covers code access security and role-based security in
greater detail.

Localization
To localize an application, you typically perform the following steps:
1. Separate your default resources from the code, and specify the localized text
in a text file.
2. Compile the text file into a .resources file.
3. Package your default resources in the main assembly by using the C#
compiler.
4. Create satellite resource assemblies, including satellites for .NET
Framework cultures, by using the Alink tool.
5. Deploy the satellites to a directory structure underneath the main
application.
6. Write the code to access the resources at run time.

For more information about localization, see the .NET Framework SDK
documentation.
34 Module 4: Deployment and Versioning

Packaging and Deployment Tools

Topic Objective
To provide a brief overview
of packaging and ! Assembly Linker (Al.exe)
deployment tools that are
included in the .NET ! Global Assembly Cache tool (Gacutil.exe)
Framework SDK.
! MSIL Disassembler (Ildasm.exe)
Lead-in
The .NET Framework SDK ! Strong Name (Sn.exe)
includes several useful tools
for examining assemblies ! Native Image Generator (Ngen.exe)
and working with the global
assembly cache. ! Assembly Binding Log Viewer (Fuslogvw.exe)
! .NET Framework Configuration Tool (Mscorcfg.msc)
! Code Access Security Policy Tool (Caspol.exe)

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework SDK includes several useful tools for examining
assemblies and working with the global assembly cache. For more information
about the tools that are introduced in this topic, see “.NET Framework Tools
and Debugger” in the .NET Framework SDK documentation.

Assembly Linker (Al.exe)

The Assembly Linker is most useful to developers who need to create a single
assembly from multiple components’ files, such as those that may be produced
with mixed-language development.

Global Assembly Cache Tool (Gacutil.exe)

The global assembly cache tool (Gacutil.exe) allows you to view and
manipulate the contents of the global assembly cache. This tool provides much
of the same cache-viewing functionality as the Windows Shell Extension
(Shfusion.dll), but the global assembly cache tool is more usable from build
scripts, makefiles, and batch files.
Specifically, Gacutil.exe allows you to install assemblies into the cache, remove
them from the cache, and list the contents of the cache. You must have
Administrator privileges on a computer to install assemblies into the global
assembly cache.
To avoid removing more than one assembly from the global assembly cache,
you can use a command with the name of your specific assembly, as follows:
gacutil /u!
hello,ver=1.0.0.1,Culture=en,PublicKeyToken=874e23ab874e23ab

The preceding command removes only the hello assembly that matches the
fully specified version number, culture, and public key.
Module 4: Deployment and Versioning 35

The following command lists the contents of the global assembly cache:
gacutil /l

MSIL Disassembler (Ildasm.exe)

You can also explore the namespaces in files that come with the runtime or in
files that you or others create by using the command-line MSIL disassembler.
To open a window that displays information about System.Data.dll, use the
following command:
>ildasm System.Data.dll

Each of the namespace nodes represents a separate namespace, which can be

expanded to explore the class objects and their methods and properties.
The MSIL disassembler also features a number of command-line options,
which are particularly useful when you want to redirect output to the console or
to a text file for subsequent analysis.

Tip Place a shortcut to Ildasm.exe in your SendTo folder.

Strong Name Tool (Sn.exe)

When working with shared components, you can use the Strong Name (Sn.exe)
command-line tool for several purposes. For example, you can use the tool to
generate a new public-private key pair and write that pair to an output file, as
follows:
sn -k <outfile>

Native Image Generator (Ngen.exe)

The Native Image Generator creates a native image from a managed assembly
and installs it into the native image cache on the local computer. Running
Ngen.exe on an assembly allows the assembly to load faster, because it restores
code and data structures from the native image cache rather than generating
them dynamically.
Pre-compiling assemblies with Ngen.exe can improve the startup time for
applications, because much of the work required to execute code has been done
in advance. Therefore, it is more appropriate to use Ngen.exe for client-side
applications where you have determined that the CPU cycles consumed by just-
in-time (JIT) compilation cause slower performance.
Because there are many factors that affect the startup time of an application,
you should carefully determine which applications would benefit from the use
of Ngen.exe. Experiment by running both a JIT-compiled and a pre-compiled
version of a candidate assembly in the environment in which it will be used.
This will allow you to compare the startup times for the same assembly
executing under different compilation schemes.
36 Module 4: Deployment and Versioning

Assembly Binding Log Viewer (Fuslogvw.exe)

The Assembly Binding Log Viewer can be used to display details for assembly
For Your Information binds. This information helps you diagnose why the .NET Framework cannot
The Assembly Binding Log
Viewer tool is used in the
locate an assembly at run time. These failures are usually the result of an
lab. assembly deployed to the wrong location or a mismatch in version numbers or
cultures.

.NET Framework Configuration Tool (Mscorcfg.msc)

The .NET Framework Configuration Tool provides a graphical interface for
managing .NET Framework security policy and applications that use remoting
services. This tool also allows you to manage and configure assemblies in the
global assembly cache. The .NET Framework Configuration Tool is a
Microsoft Management Console (MMC) snap-in.

Code Access Security Policy Tool (Caspol.exe)

The Code Access Security Policy Tool allows you to examine and modify
machine, user, and enterprise-level code access security policies. For more
information about Caspol, see Course 2350A, Securing and Deploying
Microsoft .NET Assemblies and the .NET SDK.
Module 4: Deployment and Versioning 37

Lab 4: Packaging and Deployment

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will build an
application that is named
client, which retrieves an
array of strings from an
instance of the Stringer
class and reverses the order
of these strings by using an
instance of the AReverser
class. These classes are
packaged in two separate
assembly libraries that are
named Stringer.dll and
AReverser.dll.

*ILLEGAL FOR NON-TRAINER USE**

Objectives
After completing this lab, you will be able to:
! Create an application by using private assemblies in multiple directories.
! Install and remove a strong-named assembly from the global assembly
cache.
! Configure an application to control its binding to an assembly based on the
assembly’s location and version data.

Lab Setup
Starter and solution files are associated with this lab. The starter files are in the
folder <install folder>\Labs\Lab04\Starter. The solution files are in the folder
<install folder>\Labs\Lab04\Solution.

Scenario
You will build an application that is named client, which retrieves an array of
strings from an instance of the Stringer class and reverses the order of these
strings by using an instance of the AReverser class. These classes are packaged
in two separate assembly libraries that are named Stringer.dll and
AReverser.dll.

Estimated time to complete this lab: 50 minutes

38 Module 4: Deployment and Versioning

Exercise 1
Locating Private Assemblies in Multiple Directories
In this exercise, you will build the client application by using private assemblies
that are located in multiple directories.

! Examine the application

• Open Notepad and examine the source code for the files that are listed in the
following table.
Filename Directory location

Client.cs <install folder>\Labs\Lab04\Starter\Compapp

Stringer.cs <install folder>\Labs\Lab04\Starter\Compapp\MyStringer
AReverser.cs <install folder>\Labs\Lab04\Starter\Compapp\AReverser

! Compile and build the application in a command window

1. Go to the MyStringer directory and build the private assembly library

named Stringer.dll in that directory.
2. Go to the AReverser directory and make the private assembly named
AReverser.dll in that directory.
3. Go to the Compapp directory and build the client application, referencing
the private assemblies from steps 1 and 2. Reference the DLLs in their own
directories. Do not copy them to the Compapp directory.
Module 4: Deployment and Versioning 39

! Execute the application

1. Run the Assembly Binding Log Viewer by executing Fuslogvw.exe. Click
on the right hand check box labeled Log Failures.
2. Execute the Client.exe application and note the exception in the space that is
provided.
3. In the Assembly Binding Log Viewer click on Refresh. Then double click
on the Client.exe application, and view the log entry.
4. Create a configuration file in the Client directory to specify the appropriate
privatePath so that the application can successfully bind and load the
necessary classes.
The Client.exe application should generate the following output:
Strings from StringComponent
C# String 0
C# String 1
C# String 2
C# String 3

Reversed Array Strings

C# String 3
C# String 2
C# String 1
C# String 0
40 Module 4: Deployment and Versioning

Exercise 2
Using Strong-Named Assemblies and Versioning
In this exercise, you will build the client application by using strong-named
assemblies that are located in the global assembly cache. You will then
configure an application to control its binding to an assembly based on the
assembly’s location and version data.

! Build a compatible strong-named version of AReverser

1. From a command prompt window, navigate to the <install folder>\Labs\
Lab04\Starter\Compapp directory, and use the Strong Name tool to create a
public-private key pair file that is named OrgVerKey.snk.
2. Open Notepad. On the File menu, click Open, browse to <install folder>\
Labs\Lab04\Starter\ Compapp\AReverser_v2.0.0.0, and open AReverser.cs.
3. Examine the source code and note that it is the same code that was used in
the preceding exercise.
In particular, note that the signature of the Invert method is:
public string[] Invert(string[] myString)

4. Modify the source code to specify the key pair file from step 1 and to
specify a version number of 2.0.0.0.
5. From a command prompt window, navigate to the <install folder>\Labs\
Lab04\Starter\Compapp directory and build the 2.0.0.0 strong-named
version of AReverser.cs. The AReverser.dll should be output into the
AReverser_v2.0.0.0 subdirectory.
6. Use the global assembly cache tool (Gacutil.exe) to install this assembly in
the global assembly cache.
7. Examine the global assembly cache by using Gacutil.exe or Windows
Explorer, and note the presence of AReverser and its properties.

! Build an incompatible strong-named version of AReverser

1. In Notepad, on the File menu, click Open, browse to <install folder>\
Labs\Lab04\Starter\Compapp\AReverser_v2.0.1.0, and open AReverser.cs.
2. Examine the source code and note that it is different than the code that was
used in the preceding exercise.
In particular, note that the signature of the Invert method is:
public string[] Invert(string[] myString, int myCount)

3. Modify the source code to specify the key pair file OrgVerKey.snk and to
specify a version number of 2.0.1.0.
4. From a command prompt window, navigate to the <install folder>\Labs\
Lab04\Starter\Compapp directory and build the 2.0.1.0 strong-named
version of AReverser.cs. The AReverser.dll should be output into the
AReverser_v2.0.1.0 subdirectory.
5. Install this assembly in the global assembly cache.
6. Examine the global assembly cache by using Gacutil.exe or Windows
Explorer, and note the presence of AReverser and its properties.
Module 4: Deployment and Versioning 41

! Compile, build, and execute the application

1. From a command prompt window, navigate to the Client directory and
build the client application. Reference the private assembly
MyStringer\Stringer.dll and the strong-named assembly
AReverser_v2.0.0.0\AReverser.dll.
2. Execute the Client.exe application, which should generate the following
output:
Strings from StringComponent
C# String 0
C# String 1
C# String 2
C# String 3

Reversed Array Strings

C# String 3
C# String 2
C# String 1
C# String 0

! Configure to bind to the latest version of AReverser

Tip You can obtain the publicKeyToken tag’s value by examining the global
assembly cache using gacutil /l or the cache shell extension.

1. Modify the configuration file to bind to the incompatible later version

2.0.1.0 of AReverser.
2. Execute Client.exe and note the exception.
3. Use the global assembly cache tool to remove the two strong-named
versions of AReverser.
4. Confirm the removal of the two strong-named versions of AReverser by
viewing the global assembly cache with Gacutil.exe and Windows Explorer.
42 Module 4: Deployment and Versioning

Review
Topic Objective
To reinforce module
objectives by reviewing
key points. ! Introduction to Application Deployment
Lead-in ! Application Deployment Scenarios
The review questions cover
some of the key concepts ! Related Topics and Tools
taught in the module.

*ILLEGAL FOR NON-TRAINER USE**

1. What part of the assembly identifies its imported and exported types and its
version information?
The manifest.

2. What software does a computer require to run a .NET application locally?

The .NET Framework common language runtime.

3. Name two simple ways to run a .NET Framework application.

Copy the executable file and referenced assemblies to the local
computer, or access them on a file server.
Module 4: Deployment and Versioning 43

4. Describe how an application can use an assembly that is located in an

application’s subdirectory.
Create a configuration file in the application’s directory that specifies a
PrivatePath as follows:
<configuration>
<runtime>
<assemblyBinding
xmlns="urn:schemas-microsoft-com:asm.v1">
<probing privatePath="MyStringer"/>
</assemblyBinding>
</runtime>
</configuration>

5. What kind of assembly can be placed in the global assembly cache and be
versioned?
A strong-named assembly.

6. What command is used to generate public-private key pairs?

The Strong Name (Sn.exe) tool is used to generate a new key pair and
place them in a file:
sn –k orgKey.snk

7. What command is used to install a strong-named assembly into the global

assembly cache?
> gacutil -i <filename>
THIS PAGE INTENTIONALLY LEFT BLANK
Module 5: Common
Type System

Contents

Overview 1
An Introduction to the Common Type
System 2
Elements of the Common Type System 8
Object-Oriented Characteristics 25
Lab 5: Building Simple Types 39
Review 44
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, place or event is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

 2001-2002 Microsoft Corporation. All rights reserved.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Module 5: Common Type System iii

Instructor Notes
Presentation: After completing this module, students will be able to:
90 Minutes
! Describe the difference between value types and reference types.
Lab: ! Explain the purpose of each element in the type system, including values,
45 Minutes
objects, and interfaces.
! Explain how object-oriented programming concepts, such as abstraction,
encapsulation, inheritance, and polymorphism, are implemented in the
Common Type System.

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach
this module.

Required Materials
To teach this module, you need the Microsoft® PowerPoint® file 2349B_05.ppt.

Preparation Tasks
To prepare for this module, you should:
! Read all of the materials for this module.
! Complete the lab.

Module Strategy
Use the following strategy to present this module:
! An Introduction to the Common Type System
Cover the basic architecture of the Common Type System. Introduce
System.Object as the root type for all types in the Microsoft .NET
Framework common language runtime. Explain how all types in the
Common Type System are either reference types or value types.
! Elements of the Common Type System
In this section, cover the primitive types, objects, properties, and other
elements of the Common Type System. The information will not be new to
students with a C++ object-oriented background, so you can cover these
topics quickly or omit most of the material in this section. This decision will
depend on the student’s experience.
! Object-Oriented Characteristics
Discuss how the object-oriented characteristics of the .NET Framework
common language runtime are supported. If the class is already experienced
in object-oriented techniques, you can omit this section.
Module 5: Common Type System 1

Overview
Topic Objective
To provide an overview of
the module topics and
objectives.
! An Introduction to the Common Type System
Lead-in ! Elements of the Common Type System
In this module, you will learn
about the Common Type ! Object-Oriented Characteristics
System and object-oriented
programming.

*ILLEGAL FOR NON-TRAINER USE**

In this module, you will learn about the Common Type System. Specifically,
you will learn to differentiate between value types and reference types. You will
also examine how classes, interfaces, properties, methods, events, and values
are represented in the Microsoft® .NET Framework.
After completing this module, you will be able to:
! Describe the difference between value types and reference types.
! Explain the purpose of each element in the type system, including values,
objects, and interfaces.
! Explain how object-oriented programming concepts, such as abstraction,
encapsulation, inheritance, and polymorphism, are implemented in the
Common Type System.
2 Module 5: Common Type System

" An Introduction to the Common Type System

Topic Objective
To provide an overview of
the section topics.
! Common Type System Architecture
Lead-in
In this section, you will learn ! Value Types vs. Reference Types
about the architecture of the
Common Type System.

*ILLEGAL FOR NON-TRAINER USE**

In this section, you will learn about the Common Type System architecture.
Specifically, you will learn how types are specified and represented in the .NET
Framework common language runtime, and you will learn the difference
between value types and reference types.
Module 5: Common Type System 3

Common Type System Architecture

Topic Objective
To describe the basic
architecture of the
Common Type System.
Lead-in
A type defines
characteristics for a set of
values.

*ILLEGAL FOR NON-TRAINER USE**

A type defines characteristics for a set of values. For example, the set of whole
numbers between negative 32768 and positive 32767 is called the short type in
C#, or System.Int16 in the .NET Framework class library. The short type has a
physical representation, which, in this case, is a 16-bit value. The short type
also defines operations allowed on the type, such as addition and subtraction.

System.Object
System.Object is the root type for all types in the .NET Framework common
language runtime. For this reason, any type you use will have System.Object
as its base class. System.Object has the following methods.
Methods Description

Public Equals Overloaded. Determines whether two Object

instances are equal.
Public GetHashCode Serves as a hash function for a particular type;
suitable for use in hashing algorithms and data
structures, such as a hash table.
Public GetType Gets the type of the object.
Public ReferenceEquals Determines whether the specified Object instances
are the same instance.
Public ToString Returns a string that represents the current object.
Protected Finalize Overridden. Allows an Object to attempt to free
resources and perform other cleanup operations
before the Object is reclaimed by garbage collection.
Protected MemberwiseClone Creates a shallow copy of the current Object.

For more information about the methods of System.Object, see Module 6,

“Working with Types,” in Course 2349B, Programming with the
Microsoft .NET Framework (Microsoft Visual C#™ .NET).
4 Module 5: Common Type System

Value Types
Value types are any type that inherits from System.ValueType. Value types are
typically simple types, such as integer values or long values. Value types are
special because they are allocated on the stack.
New value types are defined by using the struct or enum keywords. You
cannot create value types by using the class keyword. System.ValueType
inherits from System.Object, which means that all value types can behave like
System.Object.
The type system defines primitive types, which are Byte, Int16, Int32, Int64,
Single, Double, Boolean, Char, Decimal, IntPtr, and String. There are also
built-in types such as System.Array available.

Reference Types
Reference types are any type that inherits from System.Object and not
System.ValueType. Reference types are analogous to pointers in C++, but
there are subtle differences in the way reference types and pointers work.
Reference types are allocated on the heap. Reference types also must be
garbage collected. One example of a reference type is the System.IO file class,
which represents a file in the system.

Fields, Methods, and Properties

The Common Type System defines fields, methods, and properties that are
available to all value types and reference types. A field is a data value stored in
a class. For example, Name and Age could be fields describing an employee
stored in an Employee structure.
A method is an operation that can be performed on a class. For example, a
Tenure method could calculate how long an employee has been employed.
Properties are a convenient way to expose data values to external objects and
code. For example, the Name and Age fields could be exposed as properties,
which would allow the Employee structure to control how the name and age
are stored and retrieved.

Interfaces
Interfaces are the only types that do not inherit from System.Object. Interfaces
have no implementation; they merely provide a description of methods,
properties, and events. Any class that inherits from an interface must implement
all of the methods, properties, and events in that interface. Interfaces provide a
mechanism for specifying contractual relationships between classes. Interfaces
also provide a means of implementing multiple inheritance. For more
information about inheritance, see Module 6, “Working with Types,” in Course
2349B, Programming with the Microsoft .NET Framework (Microsoft
Visual C# .NET).
Module 5: Common Type System 5

Value Types vs. Reference Types

Topic Objective
To explain the difference
between value types and ! Value Types Are Primitive or User-Defined Structures
reference types.
# Allocated on stack
Lead-in
With the exception of # Assigned as copies
interfaces, all types in the
Common Type System are # Default behavior is pass by value
divided into two categories:
value types and reference ! Reference Types Are Objects That Are:
types.
# Allocated on heap using the new keyword
# Assigned as references
# Passed by reference

*ILLEGAL FOR NON-TRAINER USE**

With the exception of interfaces, all types in the Common Type System are
divided into two categories: value types and reference types.

Value Types
Value types represent primitive or user-defined structures. Value types are
allocated on the stack and are removed from the stack when the method call in
which they were declared returns. When a value type is passed as an argument
to a method, it is passed by value, unless the ref keyword is used. All value
types must inherit from System.ValueType.
6 Module 5: Common Type System

An integer is an example of a value type. The following example shows an

integer value type and its effect on method calls and assignment operations.
using System;

public class MainClass

{
public static void Main()
{
// Create a new integer with value 5
int a = 5;
// Create a new uninitialized integer
int b;
// Initialize b by copying the value 5 into b
b = a;
//Increase the value of b by 5
b += 5;
Console.WriteLine("{0}, {1}", a, b);
Add5(b);
Console.WriteLine("{0}, {1}", a, b);
}

public static void Add5(int num)

{
num += 5;
}
}

This code generates the following output:

5, 10
5, 10

In the preceding example, the variables a and b represent two separate instances
of the integer type. The Assignment operator (=) copies the value from one
variable to another. When the Add5 method is called, the = operator updates a
copy of the integer, not the original integer, because a copy of the value is
pushed onto the stack when passing value types.
Module 5: Common Type System 7

Reference Types
Reference types are a reference to a value. Reference types are allocated on the
heap and will remain on the heap until they are garbage collected. Reference
types must be allocated by using the new keyword. When you pass reference
types as parameters, the reference is pushed onto the stack, and the method call
works with the actual value, not with a copy of the value. All reference types
inherit from System.Object.
The following example shows the effect of assignments and method calls when
you use the StringBuilder class, which is a reference type:
using System;
using System.Text;

public class MainClass

{
public static void Main()
{
//Create a new StringBuild instance
//with the string "Bob"
StringBuilder name1 = new StringBuilder("Bob");
StringBuilder name2;
//Make name2 reference the same StringBuilder instance
name2 = name1;
name2.Append("by");
Console.WriteLine("Values are {0}, {1}", name1, name2);
Possessive(name2);
Console.WriteLine("Values are {0}, {1}", name1, name2);
}
public static void Possessive(StringBuilder name)
{
name.Append("'s");
}
}

This code generates the following output:

Values are Bobby, Bobby
Values are Bobby’s, Bobby’s

In this example, name1 and name2 always refer to the same StringBuilder
instance on the heap. Thus, whenever a change is made to the underlying
instance, both variables are affected. Also, name2 is passed by reference to the
Possessive method, so that when the Possessive method makes a change to the
instance, both name2 and name1 are affected.
8 Module 5: Common Type System

" Elements of the Common Type System

Topic Objective
To provide an overview of
the section topics and ! Primitive Types
objectives.
Lead-in ! Objects
In this section, you will learn
about primitive types, ! Constructors
objects, properties, and
! Properties
other elements of the
Common Type System. ! Custom Types
! Enumerations
! Interfaces

*ILLEGAL FOR NON-TRAINER USE**

In this section, you will learn about primitive types, objects, properties, and
other elements of the Common Type System.
Module 5: Common Type System 9

Primitive Types
Topic Objective
To explain how primitive
types are used in the
common language runtime. ! Simple Small Types Common in Most Languages
Lead-in ! Naming Differences
Primitive types in the .NET
Framework common ! C# Support
language runtime are simple
value types, commonly ! Conversions
found in most programming
languages.

*ILLEGAL FOR NON-TRAINER USE**

Primitive types in the .NET Framework common language runtime are simple
value types, which are commonly found in most programming languages.
Primitive types are simple small types, such as Boolean types or character
types.
The following table identifies all of the primitive types available in the .NET
Framework common language runtime. The table lists the Microsoft
intermediate language (MSIL) assembler name of the type, which you can see
when you view the disassembly of managed code in the MSIL Disassembler,
the name of the type in C#, the name of the type in the .NET Framework class
library, and the description of the type.
Name in Name in
MSIL Assembler Name in C# class library Description

bool bool System.Boolean True/false value

char char System.Char Unicode 16-bit char
float32 float System.Single IEEE 32-bit float
float64 double System.Double IEEE 64-bit float
int8 sbyte System.SByte Signed 8-bit integer
int16 short System.Int16 Signed 16-bit integer
int32 int System.Int32 Signed 32-bit integer
int64 long System.Int64 Signed 64-bit integer
unsigned int8 byte System.Byte Unsigned 8-bit integer
unsigned int16 ushort System.UInt16 Unsigned 16-bit integer
unsigned int32 uint System.UInt32 Unsigned 32-bit integer
unsigned int64 ulong System.UInt64 Unsigned 64-bit integer
10 Module 5: Common Type System

The following example shows how to create and initialize the primitive
System.UInt16 type in C# to store an employee’s age:
System.UInt16 age = new System.UInt16();
age = 5;

Primitive types are inherently supported in C#, allowing you to use simpler
syntax, as in the following example:
ushort age = 5;

You can convert primitive types by using the Convert class. The Convert class
defines static methods to convert from one primitive type to another. The
following example shows how to convert a long type to an unsigned short type:
long longAge = 32;
ushort ushortAge;
ushortAge = Convert.ToUInt16(longAge);

C# provides a more convenient conversion mechanism: casting. The following

example shows how to explicitly cast a long type to an unsigned short type:
long longAge = 32;
ushort ushortAge;
ushortAge = (ushort) longAge;

Casting in C# will automatically compile to conversion methods, such as

ToUInt16. Also, you can use casting to avoid memorizing the class library
names for primitive types.
Module 5: Common Type System 11

Objects
Topic Objective
To explain the role of object ! Every Class Inherits from System.Object
types in the Common Type
System. ! Objects Specify Data and Behavior
Lead-in ! Fields Define the Data
Everything in the Common
Type System is an object ! Methods Define the Behavior
and inherits from
System.Object. class
class Accumulator
Accumulator
{{
public
public float
float Result;
Result;
public
public void
void Add(float
Add(float amount)
amount)
{{
Result
Result +=
+= amount;
amount;
}}
}}

*ILLEGAL FOR NON-TRAINER USE**

Everything in the Common Type System is an object and inherits from
System.Object. An object type declaration specifies data and behavior. The
Common Type System defines data in terms of fields and defines behavior in
terms of methods. Each field or method in an object is called a member of that
object.
An object is an instance of a class. The class specifies the types that are
contained in a class and the class’s operations; an object is an instance
containing a set of data values.
In C#, you can use the class keyword to declare an object type that is a
reference type. The following example shows how to declare a class called
Accumulator.
class Accumulator
{
// Fields and methods defined here
}

Fields
Fields describe the data in an object. In the preceding example of the
Accumulator class, a field is needed to store the current result that has been
accumulated.
class Accumulator
{
public float Result;
}
12 Module 5: Common Type System

Methods
Methods describe the operations in an object. A method can have arguments
and can also have a return type. Because the Common Type System requires
strong typing, you must define a specific type for every parameter and return
value.
The following example shows how to specify an Add method for the
Accumulator class that takes an amount of type float and adds it to the Result
field.
class Accumulator
{
public float Result;
public void Add(float amount)
{
Result += amount;
}
}

The following code is an example of client code:

Accumulator calc = new Accumulator();
calc.Result = 0;
calc.Add(5);
Console.WriteLine(calc.Result);

This code generates the following output:

5
Module 5: Common Type System 13

Constructors
Topic Objective
To explain how to use
constructors to initialize ! Constructors Are Used to Initialize Classes
classes.
! Constructors Can Have Zero or More Parameters
Lead-in
If you design a class that class
class Rectangle
Rectangle
requires special initialization {{
code, you can use a private
private int
int x1,y1,x2,y2;
x1,y1,x2,y2;
constructor to initialize the public
class properly when objects public Rectangle(int
Rectangle(int x1,
x1, int
int y1,
y1, int
int x2,int
x2,int y2)
y2)
{{
are created. this.x1
this.x1 == x1;
x1;
this.x2
this.x2 == x2;
x2;
this.y1
this.y1 == y1;
y1;
this.y2
this.y2 == y2;
y2;
}}
}}

*ILLEGAL FOR NON-TRAINER USE**

If you design a class that requires special initialization code, you can use a
constructor to initialize the class properly when objects are created. A
constructor is a method with the same name as the class. The constructor runs
when a new instance of the class is created.
The following example shows how a constructor is used to initialize a class:
public class Rectangle
{
//Rectangle coordinates
private int x1,y1,x2,y2;

//Initialize coordinates in constructor

public Rectangle()
{
x1 = 0;
x2 = 0;
y1 = 0;
y2 = 0;
}
}

public class MainClass

{
public static void Main()
{
//Creating a new Rectangle
//will call constructor
Rectangle r = new Rectangle();
}
}
14 Module 5: Common Type System

Default Constructor
If you do not specify a constructor, the C# compiler will automatically provide
a default constructor. The default constructor takes no parameters and calls the
base class constructor.

Parameterized Constructor
You can also create a constructor with parameters as follows:
class Rectangle
{
//Rectangle coordinates
private int x1,y1,x2,y2;

//Initialize coordinates in constructor

public Rectangle(int x1, int y1, int x2,int y2)
{
this.x1 = x1;
this.x2 = x2;
this.y1 = y1;
this.y2 = y2;
}
}

public class MainClass

{
public static void Main()
{
//Must specify parameters
//for this constructor
Rectangle r = new Rectangle(2,2,10,10);
}
}
Module 5: Common Type System 15

Properties
Topic Objective
To describe how to use ! Properties Are Similar to Fields
properties.
Lead-in ! Properties Use get and set Accessor Methods for
Properties are values that Managing Data Values
can be stored or retrieved
on a class. public
public float
float Start
Start
{{
get
get
{{
return
return start;
start;
}}
set
set
{{
if
if (start
(start >=
>= 0)
0) start
start == value;
value;
}}
}}

*ILLEGAL FOR NON-TRAINER USE**

Properties are values that can be stored or retrieved on a class. Like fields and
methods, properties are also considered members of an object. Properties are
different than fields because access to properties is controlled through get and
set accessor methods. Also, properties are not necessarily stored in a single
variable. They may be calculated on the fly or stored in multiple variables.

get and set Accessors

Property storage and property retrieval are defined by the get and set accessor
methods. You write code in the get accessor method to determine how to
retrieve a property value. You write code in the set accessor method to
determine how to store a property value. By omitting the get or the set accessor,
you can make a property read-only or write-only.
16 Module 5: Common Type System

The following example shows how to implement a Distance class, which can
calculate the length of a trip from start to finish. The class contains three
properties: Start, Finish, and Length. The Length property is read-only and is
calculated on the fly.
class Distance
{
float start, finish;
public float Start
{
get
{
return start;
}
set
{
if (start >= 0) start = value;
}
}
public float Finish
{
get
{
return finish;
}
set
{
if (finish >= start) finish = value;
}
}
public float Length
{
get
{
return (finish - start);
}
}
}

public class MainClass

{
public static void Main()
{
Distance d = new Distance();
d.Start = 5;
d.Finish = 10;
float length = d.Length;
}
}
Module 5: Common Type System 17

In the preceding example, verification code is used in the set statements to

control how the properties are set. Negative numbers are not allowed.
Additional code could be written to throw an exception if invalid values are
used.
The client code in MainClass does not have to use method syntax with
parentheses to refer to properties.
In general, you should always use properties to expose data items to external
classes. Properties allow you to encapsulate fields, so that you can change them
in the future, if necessary.
For more information about encapsulation, see Encapsulation in this module.
18 Module 5: Common Type System

Custom Types
Topic Objective
To describe how to build ! Inherit from System.ValueType
data types that use the C#
struct keyword. ! Are Defined with the struct Keyword in C#
Lead-in
You can build your own data ! Can Have Methods, Properties, and Fields
type by using the C# struct
struct
struct Employee
Employee
keyword. {{
public
public string
string Name;
Name;
public
public ushort
ushort Age;
Age;
public
public DateTime
DateTime HireDate;
HireDate;
public
public float
float Tenure()
Tenure()
{{
TimeSpan
TimeSpan ts
ts == DateTime.Now
DateTime.Now –– HireDate;
HireDate;
return ts.Days/(float)365;
return ts.Days/(float)365;
}}
}}

*ILLEGAL FOR NON-TRAINER USE**

You can build your own data types by using the C# struct keyword. The struct
keyword will define a custom type that inherits from System.ValueType,
which in turn inherits from System.Object. All value types are sealed;
additional classes cannot be derived from them.
The following example shows how the C# struct keyword is used to build a
simple custom type that describes an individual employee:
struct Employee
{
public string Name;
public ushort Age;
public DateTime HireDate;
}

In C#, structures can also have methods as in the following example:

struct Employee
{
public string Name;
public ushort Age;
public DateTime HireDate;

public float Tenure()

{
TimeSpan ts = DateTime.Now – HireDate;
return ts.Days/(float)365;
}
}

Structures can also have properties. For example, the Employee structure could
be modified so that employee age is a property. Then the set accessor could be
used to verify that the age is a valid age.
Module 5: Common Type System 19

Enumerations
Topic Objective
To describe how to create
enumerations, which allow ! .NET Framework Enumerations
developers to specify and
represent simple types. # Inherit from System.Enum
Lead-in # Use the enum keyword
It is common for a variable
to take on only one of a ! Bit Flags
small number of values.
enum
enum SeatPreference
SeatPreference :: ushort
ushort
{{
Window,
Window, //Assigned
//Assigned value
value 00
Center,
Center, //Assigned
//Assigned value
value 11
Aisle
Aisle //Assigned
//Assigned value
value 22
}}

*ILLEGAL FOR NON-TRAINER USE**

In programming, it is common for a variable to take on only one of a small
number of values. For example, the variable for an airline passenger’s seating
preference has only three values: Window, Center, or Aisle. It is much easier
and safer for a developer to reference such values with text, rather than
numbers. The .NET Framework common language runtime supports
enumerations, which allow a developer to specify and represent these simple
types.

.NET Framework Enumerations

In the .NET Framework, enumerations inherit from the class System.Enum,
which inherits from System.ValueType. The following example shows how to
create an enumeration:
enum SeatPreference : ushort
{
Window, //Assigned value 0
Center, //Assigned value 1
Aisle //Assigned value 2
}

In the preceding example, the base type of the enumeration is defined as

ushort. You can use any simple type for a base type, except System.Char. An
enumeration will be of type int, unless otherwise specified.
The literals are specified in a comma-delimited list. Unless you specify
otherwise, the first literal is assigned a value of 0, the second a value of 1, and
so on.
20 Module 5: Common Type System

To use enumeration literals, you must fully specify the literal name as in the
following example:
SeatPreference sp;

//Assign enumerated window type seat to sp variable

sp = SeatPreference.Window;
Console.WriteLine(sp.GetHashCode());
Console.WriteLine(sp.ToString());

This code generates the following output:

0
Window

The GetHashCode method will return the literal value. By using the ToString
method, you can obtain the human-readable string name of the literal from a
variable. This feature is useful when you need to print or save a human-readable
form of the enumeration’s literals.
Also, you can use the Parse method to obtain an enumerated value from a
string. This feature is useful when receiving input in a text form that requires
conversion to the appropriate enumerated value. The following example shows
how to convert the string “center” into an enumerated value for the
SeatPreference enumeration.
sp = (SeatPreference)
System.Enum.Parse(typeof(SeatPreference), “Center”);
Module 5: Common Type System 21

Bit Flags
Enumerations in the .NET Framework are also useful for storing bit flags that
often involve bitwise operations, such as the bitwise AND operator (&), and the
bitwise OR operator (|).
Use the Flags attribute to create an enumeration of bit flags. The following
example refers to a computer-controlled weather display that uses icons to
represent weather conditions. The enumeration would allow you to combine the
icons in various ways to represent different conditions:
[Flags] enum WeatherDisplay : ushort
{
Sunny = 1,
Cloudy = 2,
Rain = 4,
Snow = 8,
Fog = 16
}

WeatherDisplay wd;
//Assign both Sunny and Cloudy attributes
//to create partly sunny forecast
wd = WeatherDisplay.Sunny | WeatherDisplay.Cloudy;
Console.WriteLine(wd.ToString());
wd = (WeatherDisplay)System.Enum.Parse(typeof(WeatherDisplay),
"Rain, Snow");
Console.WriteLine(wd.GetHashCode());

This code generates the following output:

Sunny, Cloudy
12

When using the Flags attribute, you must specify the values for the literals
manually.
22 Module 5: Common Type System

Interfaces
Topic Objective ! An Interface Is a Contractual Description of Methods
To describe the uses of
interfaces.
and Properties
Lead-in ! An Interface Has No Implementation
An interface is a contractual
description of a set of ! Use Casting in Client Code to Use an Interface
related methods and interface
interface ICDPlayer
ICDPlayer
properties. {{
void
void Play(short
Play(short playTrackNum);
playTrackNum);
void
void Pause();
Pause();
void
void Skip(short
Skip(short numTracks);
numTracks);
short
short CurrentTrack
CurrentTrack
{{
get;
get;
set;
set;
}}
}}
*****************************ILLEGAL FOR NON-TRAINER USE******************************
An interface is a contractual description of a set of related methods and
properties. An interface has a name, and it has methods and properties. For
example, an interface named ICDPlayer may have methods, such as Play,
Pause, and Skip. It may also have properties, such as CurrentTrack and
Time.
The following example shows how to define an interface called ICDPlayer that
has the methods Play, Pause, and Skip, and has the property CurrentTrack:
interface ICDPlayer
{
void Play(short playTrackNum);
void Pause();
void Skip(short numTracks);
short CurrentTrack
{
get;
set;
}
}

An interface has no implementation. Any class can inherit from any interface.
To inherit from an interface, a class must implement all methods, properties,
and events on that interface. Thus an interface serves as a contract specifying to
any user of the class that the class has implemented all methods properties, and
events defined in the interface.
Module 5: Common Type System 23

The following example shows how to implement the ICDPlayer interface in a

class called Device.
public class Device : ICDPlayer
{
// Internal property values
protected string deviceName;
protected short currentTrack;

//Constructor
public Device()
{
deviceName = "Default";
currentTrack = 1;
}

//Properties
public string DeviceName
{
get
{
return deviceName;
}
set
{
deviceName = value;
}
}
public short CurrentTrack
{
get
{
return currentTrack;
}
set
{
currentTrack = value;
}
}

//Methods
public void Play(short playTrackNum)
{
Console.WriteLine("Now Playing Track: {0}",
playTrackNum);
currentTrack = playTrackNum;
}
public void Pause()
{
Console.WriteLine("Now Paused");
}
public void Skip(short numTracks)
{
Console.WriteLine("Skipped {0} Tracks",numTracks);
}
}
24 Module 5: Common Type System

In the preceding example, all of the methods and properties of ICDPlayer were
implemented. A class may implement additional properties and methods, such
as the DeviceName property in the Device class.
Client code uses an interface by casting to the interface name. The following
example shows how a client can create an instance of the Device class and then
use the ICDPlayer interface:
public class MainClass
{
public static void Main()
{
Device Device1 = new Device();
ICDPlayer CD1 = (ICDPlayer) Device1;
//Call Play method on ICDPlayer interface
CD1.Play(1);
//Get CurrentTrack property of ICDPlayer interface
Console.WriteLine("Current Track = {0}",
CD1.CurrentTrack);
//Get DeviceName property of Device object
Console.WriteLine("Device Name = {0}",
Device1.DeviceName);
}
}

In the preceding example, the Device1 variable also could have been used to
access methods and properties of the ICDPlayer interface.
For more information about how to separate interface methods and properties
from class methods and properties, see Module 6, “Working with Types,” in
Course 2349B, Programming with the Microsoft .NET Framework (Microsoft
Visual C# .NET).
Module 5: Common Type System 25

" Object-Oriented Characteristics

Topic Objective
To provide an overview of
the topics covered in this
section. ! Abstraction
Lead-in ! Encapsulation
In this section, you will learn
how the object-oriented ! Inheritance
characteristics of the .NET
Framework common ! Polymorphism
language runtime are
supported.

*ILLEGAL FOR NON-TRAINER USE**

In this section, you will learn how the object-oriented characteristics of the
.NET Framework common language runtime are supported.
Everything in the common language runtime is an object that encompasses
fields, methods, properties, and events. Object-oriented characteristics, such as
abstraction, encapsulation, inheritance, and polymorphism, make it easier to
work with code in the .NET Framework.
26 Module 5: Common Type System

Abstraction
Topic Objective
To describe the use and
advantages of abstraction
in object-oriented ! Abstraction Works from the Specific to the General
programming.
! Grouping Elements Makes It Easier to Work with
Lead-in Complex Data Types
In object-oriented
programming, the term ! Abstraction Is Supported Through Classes
abstraction refers to the
process of reducing an
object to its essence so that
only essential elements are
represented.

*ILLEGAL FOR NON-TRAINER USE**

In object-oriented programming, the term abstraction refers to the process of
reducing an object to its essence so that only essential elements are represented.
For programmers, abstraction means working from the specific to the general.
An example of abstraction would be a phone number, such as (206) 555-1212.
At the specific level, this phone number is a sequence of numbers: 2065551212.
However, most people do not memorize phone numbers at this specific level.
Instead they memorize such information by grouping the numbers into
meaningful chunks. In this example, the phone number becomes an area code
(206), prefix (555), and number (1212). This abstraction makes it easier for a
person to remember the number. The number is reduced to three chunks to
memorize, instead of 10 individual numbers.
Abstraction is a powerful process that allows people to group and communicate
information in simpler and more meaningful ways. In the Common Type
System and other object-oriented systems, the fundamental unit of abstraction is
the class. Class types allow you to group different types of information, and
they provide the functionality to help you operate on that information. From a
design perspective, abstraction allows you to treat information and functionality
as complete functional units, rather than as disparate pieces of information and
operations.
Module 5: Common Type System 27

Encapsulation
Topic Objective
To explain the process of ! Encapsulation Is the Process of Hiding Internal Details
encapsulation in object- of a Class
oriented programming.
! Encapsulation Keywords
Lead-in
Encapsulation, or # public
information hiding, is the
process of packaging # protected
attributes and functionality
to prevent other objects # internal
from manipulating data or
procedures directly. # private
! Type-Level Accessibility
! Nested Classes

*ILLEGAL FOR NON-TRAINER USE**

In object-oriented programming, encapsulation, or information hiding, is the
process of packaging attributes and functionality to prevent other objects from
manipulating data or procedures directly. Encapsulation also allows the object
that is requesting service to ignore the details of how the service is provided. By
hiding the internal unnecessary data and functionality of a class from other
classes, encapsulation provides greater flexibility in the design of classes. For
example, when a sorting class performs sorts on data items, the internal data
structure of the class will probably store the data items, such as a linked list.
The class will also have internal functions that operate on the linked list.
If clients that use the sorting class have direct access to the linked list, they will
incorporate code that relies on the linked list. In fact, if no accessor functions
are written for the linked list, the clients must use the linked list to store or
retrieve data items.
If the sorting class changes in the future, it may change the linked list to an
array for optimization, and the clients will stop functioning correctly. At that
time, the clients would require rewriting to use the array syntax. If the sorting
class hid the internals of its implementation and provided accessor functions
that mapped to the internal data structure, this problem could be avoided.
C# provides a set of access modifiers that vary the degree of accessibility to
members of any type. The following table lists all of the access modifiers
supported in C#.
Access
modifier Description

public Makes a member available to all other classes in all assemblies

protected Makes a member available only to classes that inherit from this class
internal Makes a member available only to other classes in the same assembly
private Makes a member available only to the same class
28 Module 5: Common Type System

If no access modifier is specified, a default modifier is applied. The following

table shows which modifiers are applied to different types by default.
Members of Default member accessibility

enum public
class private
interface public
struct private

Type-Level Accessibility
You can specify accessibility at the type level and at the member level. Access
modifiers can be applied to enumerations, classes, interfaces, and structs.
However, for top-level types, internal and public are the only allowed
modifiers. You cannot create a private class or a protected interface at the top
level in a namespace.
The access modifier applied at the type level will supercede member-level
access modifiers if the type-level access modifier is more restrictive. For
example, an internal class can have a public method, but the internal modifier
will make the public method internal as well.
The following example shows the effect of applying access modifiers at the
class level and the member level:
public class COuter1
{
public static short MyPublicShort = 0;
internal static short MyInternalShort = 0;
private static short MyPrivateShort = 0;
}

public class MainClass

{
public static void Main()
{
COuter1.MyPublicShort = 1;
//Success because publicly available
COuter1.MyInternalShort = 2;
//Success because in same assembly
COuter1.MyPrivateShort = 3;
//Failure because private only available to COuter1 class
}
}
Module 5: Common Type System 29

Nested Classes
When classes are nested, the nested classes cannot exceed the accessibility of
the containing class. For example, if a nested class is marked as public, but the
containing class is marked as internal, the nested class must also be internal.
The following example shows the effect of access modifiers on nested classes:
internal class COuter1
{
public class CInner1
{
public static short MyPublicShort = 0;
internal static short MyInternalShort = 0;
private static short MyPrivateShort = 0;
}
internal class CInner2
{
public static short MyPublicShort = 0;
internal static short MyInternalShort = 0;
private static short MyPrivateShort = 0;
}
private class CInner3
{
public static short MyPublicShort = 0;
internal static short MyInternalShort = 0;
private static short MyPrivateShort = 0;
}
}

public class MainClass

{
public static void Main()
{
COuter1.CInner1.MyPublicShort = 1;
//Success because internal at class level
//and in same assembly

COuter1.CInner2.MyPublicShort = 2;
//Success because internal and in same assembly

COuter1.CInner3.MyPublicShort = 3;
//Failure because class is private, and all members are
private
}
}
30 Module 5: Common Type System

Inheritance
Topic Objective
To explain how inheritance
works in the Common Type ! Inheritance Is the Reuse of Class Members in
System. Other Classes
Lead-in ! The Common Type System Only Supports Single
Inheritance is a method of Inheritance for Classes
reuse that enables one
class to reuse, or inherit, the ! Member Hiding
fields, properties, and
methods of another class. # Redefine the same method in the derived class
# Use the new keyword
! Abstract Members
! Sealed Classes

*ILLEGAL FOR NON-TRAINER USE**

In object-oriented programming, inheritance is a method of reuse that enables
one class to reuse, or inherit, the fields, properties, and methods of another
class. Inheritance represents an “is a” relationship between classes. For
example, if a square class inherits from a shape class, the square “is a” kind of
shape.
Inheritance is useful when multiple classes share the same methods or data. The
common methods and data can be abstracted into a separate class that the other
classes inherit from.
Inheritance is pervasive in the Common Type System. Every class must inherit
from System.Object, so all classes will have the members of System.Object.

Single Inheritance
The Common Type System only supports single inheritance of class types.
Single inheritance means a class can inherit directly from only one other class.
Some object-oriented systems, such as C++, allow multiple inheritance, which
means that one class can inherit from many other classes.
The Common Type System does support multiple inheritance through
interfaces. In that case, one class can inherit from one other class and from zero
or more interfaces. For more information about multiple inheritance through
interfaces, see Module 6, “Working with Types,” in Course 2349B,
Programming with the Microsoft .NET Framework (Microsoft Visual C#
.NET).
In the simplest form of inheritance, a class inherits its members from the base
class and gains all the functionality of the base class, and at the same time it
adds additional functionality of its own.
Module 5: Common Type System 31

In the following example, three classes are defined. The base class is called
Animal; it implements an Age property and a Move method. The second class
is called Dog; it inherits from Animal and implements an additional method
called Bark. The third class is called Cat; it also inherits from Animal and
implements an additional method called Meow.
public class Animal
{
protected short age = 0;
public short Age
{
get
{
return age;
}
set
{
if (value > 0) age = value;
}
}
public void Move()
{
Console.WriteLine("Animal is Moving");
}
}

public class Dog : Animal

{
public void Bark()
{
Console.WriteLine("Bark!");
}
}

public class Cat : Animal

{
public void Meow()
{
Console.WriteLine("Meow!");
}
}

public class MainClass

{
public static void Main()
{
Dog d = new Dog();
Cat c = new Cat();
d.Age = 3;
d.Move();
d.Bark();
c.Age = 2;
c.Move();
c.Meow();
}
}
32 Module 5: Common Type System

This code generates the following output:

Animal is Moving
Bark!
Animal is Moving
Meow!

In the Main method, a Dog object and Cat object are created. Methods and
properties of the Animal class are called on the Dog object and the Cat object.
In this way, the Animal class functionality for storing the age of an animal and
implementing movement in an animal can be written once and reused in
multiple classes.

Member Hiding
Sometimes you will want a class to inherit from a base class, but you will want
to modify some of the base class’s functionality. For example, you may want a
new kind of animal class called Slug to inherit from the Animal class, but you
will want to use the Move method to make the slug move slowly. You can
accomplish this effect by creating a method with the same name and parameter
list as the base class method.
The following example shows how you can customize the Move method for
slugs by making the Slug class replace the Move method of the Animal class:
public class Slug : Animal
{
public new void Move()
{
Console.WriteLine("Moving very slowly");
}
}

public class MainClass

{
public static void Main()
{
Slug s = new Slug();
s.Move();
}
}

This code generates the following output:

Moving very slowly

In the preceding example, the new keyword is used to signal that a method was
replaced. In this context, the new keyword denotes that a method was hidden.
This use of the new keyword should not be confused with the use of the new
keyword to allocate a new object. While the new keyword is not required for
method hiding, it enhances readability. The C# compiler will issue a warning if
the new keyword is not used on replaced methods.
Module 5: Common Type System 33

Abstract Members
Methods, fields, and properties can also be abstract. A method, field, or
property is abstract when the base class does not implement the member, and
the derived class must implement the member.
Abstract members are marked with the abstract keyword. When derived
classes implement abstract methods, they must use the override keyword to
indicate that they are overriding the base-class functionality.
The following example shows an abstract Shape class that has one abstract
method called Draw. The Shape class implements a Move method, which,
when called, will call the derived class Draw method. Thus the Shape class has
information about how to move but does not have information about how to
draw after it moves. The abstract method forces the derived class to implement
the Draw method so that the Shape class can move properly.
using System;

abstract class Shape

{
protected int x, y;

//Derived class must implement next method

public abstract void Draw();
public void Move(int x, int y)
{
this.x = x;
this.y = y;
//Call derived class implementation
Draw();
}
}

class Square : Shape

{
public override void Draw()
{
Console.WriteLine("Drawing a Square at {0},{1}",x,y);
}
}

class MainClass
{
public static void Main()
{
Square s = new Square();
//Call base class Move method, which in turn calls
//derived class Draw method
s.Move(1,1);
}
}
34 Module 5: Common Type System

This code generates the following output:

Drawing a Square at 1,1

If a class contains any abstract members, the entire class becomes an abstract
class. As a result, an instance of the abstract class cannot be created because it
is missing functionality for a method. For this reason, the Shape class in the
preceding example was marked as abstract.

Sealed Classes
You can prevent other classes from deriving from a specific class by sealing
that class. Use the sealed modifier to make a sealed class.
sealed class SealedClass
{
public static void Foo()
{
}
}

The sealed modifier is primarily used to prevent unintended derivation, but it

also enables certain run time optimizations. In particular, because a sealed class
is known to never have any derived classes, it is possible to transform virtual
function member invocations on sealed class instances into non-virtual
invocations.
Module 5: Common Type System 35

Polymorphism
Topic Objective
To explain the use of
polymorphism to define a
base class. ! Polymorphism Allows a Reference Variable to Call the
Correct Method
Lead-in
In object-oriented ! Virtual Methods Enable Polymorphism in the Common
programming, polymorphism Type System
allows you to define a base
class that includes routines # Use the virtual keyword in the base class
that perform standard
operations on groups of # Use the override keyword in the derived class
related objects, without
regard to the exact type of ! Sealed Methods
each object.

*ILLEGAL FOR NON-TRAINER USE**

Polymorphism derives from the Greek for “many forms.” In object-oriented
programming, polymorphism allows you to define a base class that includes
routines that perform standard operations on groups of related objects, without
regard to the exact type of each object. For example, in the preceding animal
scenario, you could add a method called MakeNoise. When this method is
called, Animal objects should print “Animal is making noise.” A dog object
should print “Bark!”, and a cat object should print “Meow!”
In the following example, the code does not work as expected; it prints “Animal
is making noise,” instead of the desired specific animal noise, such as “Bark” or
“Meow”:
public abstract class Animal
{
//..Other properties and methods
public void MakeNoise()
{
Console.WriteLine("Animal is making noise");
}
}

public class Dog : Animal

{
//..Other properties and methods
public new void MakeNoise()
{
Console.WriteLine("Bark!");
}
}

(Code continued on the following page.)

36 Module 5: Common Type System

public class Cat : Animal

{
//..Other properties and methods
public new void MakeNoise()
{
Console.WriteLine("Meow!");
}
}

public class MainClass

{
public static void Main()
{
Dog d = new Dog();
Cat c = new Cat();
d.Age = 3;
c.Age = 2;
WorkWithAnimal(d);
WorkWithAnimal(c);
}
public static void WorkWithAnimal(Animal a)
{
Console.WriteLine("Working with animal age {0}",a.Age);
a.MakeNoise();
}
}

This code generates the following output:

Working with animal age 3
Animal is making noise
Working with animal age 2
Animal is making noise

In the preceding example, because the reference in the WorkWithAnimal

method is type Animal, the Animal base class MakeNoise always gets called.
The desired behavior would be a dog object making a noise like a dog, not an
animal.
Module 5: Common Type System 37

To resolve this problem, use the virtual keyword to mark a method as virtual.
Using the virtual keyword will ensure that the correct method call gets called
on the basis of the object type, not the reference type. The derived class must
then use the override keyword on the same method, as in the following
example:
public abstract class Animal
{
//..Other properties and methods
public virtual void MakeNoise()
{
Console.WriteLine("Animal is making noise");
}
}

public class Dog : Animal

{
//..Other properties and methods
public override void MakeNoise()
{
Console.WriteLine("Bark!");
}
}

public class Cat : Animal

{
//..Other properties and methods
public override void MakeNoise()
{
Console.WriteLine("Meow!");
}
}

public class MainClass

This code generates the following output:

Working with animal age 3
Bark!
Working with animal age 2
Meow!

Sealed Methods
You can use the sealed modifier to prevent derived classes from overriding
specific methods. Methods marked with the sealed modifier are called sealed
methods. The sealed modifier can only be used in conjunction with the
override modifier.
class A
{
public virtual void Foo()
{/*...*/
}
}
class B : A
{
//Any class derived from B will
//not be able to override Foo
public sealed override void Foo()
{/*..*/
}
}
Module 5: Common Type System 39

Lab 5: Building Simple Types

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will create
simple types and
enumerations, and work
with inheritance.

*ILLEGAL FOR NON-TRAINER USE**

Objectives
After completing this lab, you will be able to:
! Create enumerations.
! Create custom value types as structures.
! Inherit from a base class and override properties and methods.
! Create constructors.
! Use appropriate levels of encapsulation through the private and public
access modifiers.

Prerequisites
Before working on this lab, you must have:
! Knowledge about how to use Microsoft Visual Studio® .NET for creating
and working with console applications.
! Knowledge about the C# language.
! Knowledge about the System.Console namespace for interacting with the
console.

Estimated time to complete this lab: 45 minutes

40 Module 5: Common Type System

Exercise 1
Creating an Enumeration
In this exercise, you will create a simple program that uses an enumeration to
reference weekdays. You will enumerate the weekdays, Monday through
Friday, as a type. Then you will write code to accept a day from the user, match
the day to the enumerated type, and write a response back to the user.

! Create an enumeration
1. Open the Days project located in the folder <install folder>\Labs\Lab05\
Starter\Days.
2. Open the Main.cs file.
3. Create an enumeration called Weekdays. The enumeration should be of
type int and should enumerate the literals Monday, Tuesday, Wednesday,
Thursday, and Friday.

! Use an enumeration
1. Locate the Main method of the MainClass class.
2. In the Main method, write code to perform the following tasks:
a. Write a question to the console that reads, “What day of the week is it?”
b. Use the Console.ReadLine method to get the user’s response.
c. Determine which day the user selected by parsing the Weekdays
enumeration. Store the correct Weekdays literal in a variable of type
Weekdays.
d. Use a switch statement on the mapped response to determine which day
of the week it is. Based on the response, write a string to the user. For
example, for Monday, write “Monday is the first weekday.” For
Tuesday, write “Tuesday is the second weekday,” and so on.
3. Compile and test the code. Run the program and type in a weekday. You
should get an appropriate response based on the day you entered.
Module 5: Common Type System 41

Exercise 2
Creating a Custom Value Type
In this exercise, you will create a custom value type or structure to represent a
complex number. Complex numbers have a real part and an imaginary part.
You will design the structure to store the real and imaginary parts, and you will
perform addition on complex numbers.

! Create a structure
1. Open the Complex project located in the folder <install folder>\Labs\
Lab05\Starter\Complex.
2. Open the Main.cs file.
3. Create a new structure called Complex.
a. Create a public member variable called Real of type int.
b. Create a public member variable called Imaginary of type int.
4. Create an overloaded Addition operator (+) for the Complex structure. The
overloaded operator should look as follows:
public static Complex operator +(Complex c1, Complex c2)
{
}

a. In the Addition operator method, create a variable called result of type

Complex to hold the result of the addition.
b. Add c1.Real to c2.Real and store the result in result.Real.
c. Add c1.Imaginary to c2.Imaginary and store the result in
result.Imaginary.
d. Return the result.

! Use the structure

1. Locate the Main method in the MainClass class.
2. In the Main method, write code to create a variable called num1 of type
Complex.
3. Create a second variable called num2 of type Complex.
4. Initialize num1 and num2 with real and imaginary parts. For example,
num1 could have values of 2 and 3 for the real and imaginary parts. num2
could have values of 3 and 4 for the real and imaginary parts.
5. Add the two numbers together, and print both the real and imaginary parts.
6. Compile the program and run it. Verify that the result is correct. Using the
values in step 4, you should see the results of 5 and 7 for the real and
imaginary parts.
42 Module 5: Common Type System

Exercise 3
Creating Objects
In this exercise, you will derive new classes from base classes and then use the
derived classes. You will work with a base class called Polygon. The class
represents the geometric characteristics of polygons.
Polygons have a number of sides. Thus the Polygon class defines a NumSides
property but does not implement it. The derived classes implement the
NumSides property. For example, a Triangle class could be created that
overrides the NumSides property and initializes it to 3. A Pentagon class could
be created that overrides the NumSides property and initializes it to 5.
The Polygon class also implements a Degrees property that returns the sum of
all the angles in the polygon. For example, the angles in a triangle always add
up to 180 degrees. This simple calculation is based on the number of sides in
the polygon, and so the derived class must implement the NumSides property.
The Polygon class also defines an abstract method called Area that will return
the area of the polygon. The derived class must override this method to
calculate the correct area.

! Derive a new class

1. Open the Shapes project located in the folder <install folder>\Labs\Lab05\
Starter\Shapes.
2. Open the Polygon.cs file and study the code for the Polygon class. Notice
that it is an abstract class that has an abstract property called NumSides, a
property called Degrees, and an abstract method called Area that returns the
area inside the polygon.
3. Open the Main.cs file.
4. Create a new class called Square that inherits from Polygon.
a. Create private member variables called x1, y1, and size of type int to
store the Cartesian coordinates of the upper-left corner and the size of
the square, which is the length of one side.
b. Create a private member variable called numSides of type ushort to
store the number of sides that the square has.
c. Create a constructor that accepts three integer parameters (x1, y1, size) to
construct a new square. Initialize the private member variables to the
values passed as parameters. Initialize numSides to 4.
d. Override the NumSides property in the base class to return the
numSides variable.
e. Create read/write properties called X1, and Y1 respectively that map to
the private variables x1, and y1.
f. Create two read-only properties called X2 and Y2. These represent the
lower-right coordinate of the square and are calculated by adding size to
x1 or y1 respectively.
g. Override the Area method to return the area of the square. The area can
be calculated with the following formula: (size)2.
Module 5: Common Type System 43

! Use the derived class

1. Locate the Main method in the MainClass class.
2. In the Main method, write code to create a new Square object. Initialize the
square with values for the upper-left corner and size, such as 1, 1, and 4.
3. Write the number of degrees in the square to the console by printing the
Degrees property.
4. Write the area to the console by calling the Area method.
5. Write the x1, y1, x2, y2 coordinates to the console by using the properties of
the square object.
6. Compile the program and test it. Verify that all the methods and properties
work as expected. Given a square with upper-left coordinates of 1, 1, and a
size of 4, the number of degrees is 360, the area is 16, and the lower-right
coordinates are 5, 5.
44 Module 5: Common Type System

Review
Topic Objective
To reinforce module
objectives by reviewing
key points. ! An Introduction to the Common Type System
Lead-in ! Elements of the Common Type System
The review questions cover
some of the key concepts ! Object-Oriented Characteristics
taught in the module.

*ILLEGAL FOR NON-TRAINER USE**

1. What are the differences between value types and reference types?
Value types are allocated on the stack, assigned as copies, and passed by
value.
Reference types are allocated on the heap, assigned as references, and
passed by reference.

2. What are the differences between fields and properties?

A field is a data value in a class that can be directly accessed and
manipulated by other classes.
A property is a value in a class that is accessed through get and set
accessor methods. The actual data value of a property may be stored in
the class instance, or calculated when accessed.

3. How do you create an enumeration in C#?

Use the enum keyword:
enum name : type
{
…literals…
}
Module 5: Common Type System 45

4. What is an interface?
An interface is a contractual description of a set of related methods and
properties.

5. How is encapsulation supported by the .NET Framework?

Encapsulation is supported through access modifiers, such as public,
protected, internal, and private.
THIS PAGE INTENTIONALLY LEFT BLANK
Module 6:
Working with Types

Contents

Overview 1
System.Object Class Functionality 2
Specialized Constructors 12
Type Operations 18
Interfaces 28
Managing External Types 34
Lab 6: Working with Types 38
Review 43
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, place or event is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

 2001-2002 Microsoft Corporation. All rights reserved.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Module 6: Working with Types iii

Instructor Notes
Presentation: After completing this module, students will be able to:
75 Minutes
! Apply attributes to control visibility and inheritance in classes and
Lab: interfaces.
45 Minutes
! Create and use interfaces that define methods and properties.
! Explain how boxing and unboxing works and when it occurs.
! Use operators to determine types at run time and cast values to different
types.
! Explain what features are available to work with unmanaged types, such as
COM types.

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach
this module.

Required Materials
To teach this module, you need the Microsoft® PowerPoint® file 2349B_06.ppt.

Preparation Tasks
To prepare for this module, you should:
! Read all of the materials for this module.
! Complete the lab.
iv Module 6: Working with Types

Module Strategy
Use the following strategy to present this module:
! System.Object Class Functionality
In this section, discuss how System.Object provides classes to generate
hash functions, represent strings, and compare objects for identity and
equality.
Explain that this section does not cover all of the classes in System.Object,
and that other classes are covered elsewhere in the course. For example,
finalization and the Finalize method are covered in detail in Module 9,
“Memory and Resource Management,” in Course 2349B, Programming
with the Microsoft .NET Framework (Microsoft Visual C#™ .NET).
! Specialized Constructors
This section covers more advanced types of constructors. Explain how static
constructors work, when to use them, and when to use private constructors.
If the students in your class already have experience in C++, you may not
need to spend much time on these topics.
! Type Operations
The Microsoft .NET Framework common language runtime supports a
variety of type operations for working with types. Discuss conversions and
conversion operators for determining and converting the type of an object.
Also cover how to cast types for conversion and for treating a type as a
different type.
For experienced C++ programmers, you may be able to cover type
conversion and casting quickly. C++ programmers may find it useful that
the as operator in C# is similar to dynamic_cast in C++.
Spend most of this section discussing boxing and unboxing. Students will
need to be aware of the performance consequences of boxing. Explain how
you can avoid or minimize these consequences if you must use boxing.
! Interfaces
Discuss how multiple inheritance works through interfaces and explain how
to explicitly implement interfaces.
As with the other topics in this module, you may be able to cover this
section quickly if your audience is already familiar with object-oriented
programming techniques.
For experienced C++ programmers, consider mentioning that explicit
interface implementation was not possible in C++.
! Managing External Types
Briefly introduce Platform Invocation Services and COM interoperability.
Be aware that more information about these topics is available in Module
15, “Interoperating Between Managed and Unmanaged Code,” in Course
2349B, Programming with the Microsoft .NET Framework (Microsoft
Visual C# .NET) and “Interoperating with Unmanaged Code” in the .NET
Framework SDK documentation.
Module 6: Working with Types 1

Overview
Topic Objective
To provide an overview of
the module topics and
objectives.
! System.Object Class Functionality
Lead-in ! Specialized Constructors
In this module, you will learn
how to apply your ! Type Operations
knowledge of the Common
Type System to various ! Interfaces
programming scenarios.
! Managing External Types

*ILLEGAL FOR NON-TRAINER USE**

In this module, you will learn how to apply your knowledge of the Common
Type System to various programming scenarios. This module will help you
understand how to use types efficiently when developing Microsoft® .NET
Framework applications. You should understand that many nuances in the type
system can affect program clarity and performance if ignored.
This module covers the use of attributes to control visibility and inheritance on
types and explains how to work with various type operations, such as boxing
and unboxing, and type operators. The module then explores how to work with
types programmatically by using operators to coerce, cast, or discover types at
run time.
In addition, this module discusses how to build an interface that supports
methods and properties and how to make interface designs more efficient.
The module also highlights features that are designed to help you work with
unmanaged types, such as COM types.
After completing this module, you will be able to:
! Apply attributes to control visibility and inheritance in classes and
interfaces.
! Create and use interfaces that define methods and properties.
! Explain how boxing and unboxing works and when it occurs.
! Use operators to determine types at run time and cast values to different
types.
! Explain what features are available to work with unmanaged types, such as
COM types.
2 Module 6: Working with Types

" System.Object Class Functionality

Topic Objective
To provide an overview of
the topics covered in this
section. ! Hash Codes
Lead-in ! Identity
In this section, you will learn
about the common methods ! Equality
that you need to override on
the System.Object class. ! String Representation

*ILLEGAL FOR NON-TRAINER USE**

In this section, you will learn about the common methods that you need to
override on the System.Object class.
This section does not cover finalization and the Finalize method, which are
covered in detail in Module 9, “Memory and Resource Management,” in
Course 2349B, Programming with the Microsoft .NET Framework (Microsoft
Visual C#™ .NET). Also, this section does not cover the MemberwiseClone
method.
Module 6: Working with Types 3

Hash Codes
Topic Objective
To explain how to use hash ! Hash Code Used to Perform Quick Lookups
codes to perform quick
lookups in tables and other ! Override GetHashCode Method on System.Object
types of collections.
Lead-in ! Should Return Same Hash Code for Objects of
A hash function is used to Same Value
quickly generate a number,
or hash code, that
! Should Implement Efficient Algorithm
corresponds to the value of
an object. struct
struct Student
Student {{
string
string name;
name;
int
int ID;
ID; //Unique
//Unique for
for each
each instance
instance
public
public override
override int
int GetHashCode()
GetHashCode() {{
return
return ID;
ID;
}}
}}

*ILLEGAL FOR NON-TRAINER USE**

A hash function is used to quickly generate a number, or hash code, that
corresponds to the value of an object. Hash codes are useful for performing
quick lookups in tables, such as the HashTable class, and other kinds of
collections.
A hash table uses the hash code to drastically limit the number of objects that
must be searched to find a specific object in a collection of objects. The hash
table does this by getting the hash value of the object and eliminating all objects
with a different hash code. This preliminary search leaves only those objects
with the same hash code to be searched. Because there are few instances with
that hash code, searches are much quicker.
System.Object provides a GetHashCode method, which returns an int type.
You should override this method to return a hash code on any custom classes or
structures that you create. One reason for overriding this method is that when
two objects are equal in value, you should get the same hash code for each
object if you call GetHashCode. In the case of custom objects, the default
implementation of GetHashCode does not give you the same hash code for two
objects that are equal in value.
4 Module 6: Working with Types

A good hash code algorithm will support the best performance by generating a
random distribution for all input. You should base your hash code algorithm on
one of the unique fields in the class. Also, you should never throw an exception
from the GetHashCode method because GetHashCode can be called
frequently and should always work reliably.
The following example shows how to implement GetHashCode for a Student
structure that stores a student’s name and ID.
struct Student
{
string name;
int ID; //Unique for each instance
public override int GetHashCode()
{
return ID;
}
}
Module 6: Working with Types 5

Identity
Topic Objective
To explain how identity is
determined in the .NET
Framework common ! Compare to Determine If Two References Are Actually
language runtime. the Same Object
Lead-in ! Use the Object.ReferenceEquals Method to Test Identity
There are two kinds of
comparison for objects:
identity and equality. This
topic covers object identity.

*ILLEGAL FOR NON-TRAINER USE**

There are two kinds of comparison for objects: identity and equality. This topic
covers object identity.

Determining Identity
Two objects are identical if they are, in fact, the same object. Every object in
the .NET Framework common language runtime has an identity that makes it
unique in the system.
In C++, an object’s identity is determined by its address. Thus, if two pointers
are compared and contain the same address, they point to the same object.
In COM, an object’s identity is determined by the IUnknown interface. Thus, if
two IUnknown interface pointers are compared and contain the same address,
they are the same COM object.
In the .NET Framework common language runtime, you can use the
Object.ReferenceEquals method to compare for identity. Internally,
ReferenceEquals compares the addresses of the objects in memory to
determine if they are the same object. If they are the same object,
ReferenceEquals returns true.
6 Module 6: Working with Types

Using the Object.ReferenceEquals Method

In the following example, a value type variable called x is created and passed in
two parameters to the Test method. The Test method compares the two
parameters to determine if they are identical.
class MyObject
{
public int X;
}

class MainClass
{
public static void Main()
{
MyObject obj1 = new MyObject();
obj1.X = 5;
Test(obj1, obj1);
MyObject obj2 = new MyObject();
obj2.X = 5;
Test(obj1, obj2);
}
public static void Test(MyObject a, MyObject b)
{
if (Object.ReferenceEquals(a,b))
Console.WriteLine("Identical");
else
Console.WriteLine("Not Identical");
}
}

This code generates the following output:

Identical
Not Identical
Module 6: Working with Types 7

Equality
Topic Objective
To explain how to override ! Comparing Two Objects to Determine If They Are Equal
the Equals method and to
introduce guidelines for ! Override the Equals Method
implementing code to
provide equality comparison ! Supply == and != Operators
for types. ! Guidelines
Lead-in
Objects can also be
# If overriding Equals, override GetHashCode
compared for equality. # If overloading ==, override Equals to use same
algorithm
# If implementing IComparable, implement Equals
# Equals, GetHashCode, and == operator should never
throw exceptions

*ILLEGAL FOR NON-TRAINER USE**

Objects can also be compared for equality. The Object.Equals method,
equality operator (==), or inequality operator (!=) are used to test equality.

Equals Method
The Equals method is part of the Object class. You should override this
method in your classes and structures to perform appropriate behavior when
comparing objects of certain types. The default Object.Equals method calls
Object.ReferenceEquals, which results in an identity comparison instead of a
value comparison. In general, you should also override the == and != operators
to allow easier syntax to compare objects.
8 Module 6: Working with Types

The following example shows how to override the Equals method and the ==
and != operators to test user-defined Rectangle objects for equality.
class Rectangle
{
//Rectangle coordinates
public int x1,y1,x2,y2;
public Rectangle(int x1, int y1, int x2, int y2)
{
this.x1 = x1;
this.x2 = x2;
this.y1 = y1;
this.y2 = y2;
}
public override int GetHashCode()
{
return x1;
}
public override bool Equals (Object obj)
{
//Check for null and compare run-time types.
if (obj == null || GetType() != obj.GetType()) return
false;
Rectangle r = (Rectangle)obj;
return (x1 == r.x1) && (y1 == r.y1) && (x2 == r.x2) &&
(y2 == r.y2);
}
static public bool operator == (Rectangle r1, Rectangle r2)
{
//Check for null parameters
//Cast to object to avoid recursive call
if ((object)r1 == null) return false;
//Let Equals method handle comparison
return r1.Equals(r2);
}
static public bool operator != (Rectangle r1, Rectangle r2)
{
//Check for null parameters
//Cast to object to avoid recursive call
if ((object)r1 == null) return true;
//Let Equals method handle comparison
return !r1.Equals(r2);
}
}

class MainClass
{
public static void Main()
{
Rectangle r1 = new Rectangle(5,5,50,55);
Rectangle r2 = new Rectangle(5,5,50,55);
Console.WriteLine(r1.Equals(r2));
Console.WriteLine(r1 == r2);
Console.WriteLine(null == r1);
}
}
Module 6: Working with Types 9

This code generates the following output:

True
True
False

Guidelines for Equality Comparison

Use the following guidelines when implementing code to provide equality
comparison for types.
! Anytime you override the Equals method, also override the GetHashCode
method. If two objects are equal, they must return the same hash code. The
default implementation of GetHashCode does not return the same value.
! Anytime you overload the == operator, also override the Equals method
and the != operator to use the same algorithm. This technique allows
infrastructure code, such as HashTable and ArrayList classes, that uses the
Equals method, to behave in the same manner as user code that is written
with the == operator.
! Anytime you implement the IComparable interface, also implement the
Equals method, and ensure that both elements use the same algorithm for
comparisons. You should also consider overloading the comparison
operators because any client code that uses the IComparable interface is
also likely to use these operators.
! The Equals method, GetHashCode method, and comparison operators
should never throw an exception. Exceptions in comparison operators can
cause confusion because most programmers do not anticipate these types of
exceptions. Also, these methods are called frequently and need to be
efficient and clean to avoid writing additional error-handling code for what
are considered simplistic methods.
10 Module 6: Working with Types

String Representation
Topic Objective
To explain how the ! Override ToString to Customize String Form of a Class
ToString method is used in
the .NET Framework struct
struct President
President
common language runtime. {{
Lead-in public
public string
string FirstName;
FirstName;
All objects have the ability to public
public string LastName;
string LastName;
represent themselves in a public
public override
override string
string ToString()
ToString()
string form. {{
return
return FirstName
FirstName ++ "" "" ++ LastName;
LastName;
}}
}}

! Use IFormattable Interface and ToString Method for

Localized Strings

*ILLEGAL FOR NON-TRAINER USE**

One characteristic of all objects is the ability to represent themselves in a string
form. The ToString method provides this ability for all objects. Methods in the
Microsoft .NET Framework common language runtime, such as
Console.WriteLine, frequently use ToString. The ToString method also is
useful for debugging.
The default behavior of the Object.ToString method is to return the name of
the class. The following example shows what happens when ToString is called
on a President structure.
struct President
{
public string FirstName;
public string LastName;
}
class MainClass
{
public static void Main()
{
President firstPres;
firstPres.FirstName = "George";
firstPres.LastName = "Washington";
Console.WriteLine(firstPres.ToString());
}
}

This code generates the following output:

President
Module 6: Working with Types 11

You can override the ToString method to provide custom behavior, as shown
in the following example:
struct President
{
public string FirstName;
public string LastName;
public override string ToString()
{
return FirstName + " " + LastName;
}
}
class MainClass
{
public static void Main()
{
President firstPres;
firstPres.FirstName = "George";
firstPres.LastName = "Washington";
Console.WriteLine(firstPres.ToString());
}
}

This code generates the following output:

George Washington

If an object needs to be represented in localized string forms, you should not

override Object.ToString. Instead, you should implement the IFormattable
interface and its ToString method. The IFormattable interface can take into
account different locales.
12 Module 6: Working with Types

" Specialized Constructors

Topic Objective
To provide an overview of
the topics covered in this
section. ! Static Constructors
Lead-in ! Private Constructors
This section covers more
advanced types of
constructors. It explains how
static constructors work,
when to use them, and
when to use private
constructors.

*ILLEGAL FOR NON-TRAINER USE**

This section covers more advanced types of constructors. It explains how static
constructors work, when to use them, and when to use private constructors.
Module 6: Working with Types 13

Static Constructors
Topic Objective
To explain how static
constructors work. ! Used to Initialize Static Members
Lead-in
class
class DeviceConnection
DeviceConnection
Static constructors are used
to initialize static fields. {{ public
public static
static uint
uint ConnectionCount;
ConnectionCount;
public
public void OpenConnection(string connectionName)
void OpenConnection(string connectionName)
{{ ConnectionCount++;
ConnectionCount++;
//Other
//Other work
work to
to open
open device
device }}
static
static DeviceConnection()
DeviceConnection()
{{ //Initialize
//Initialize static
static members
members
ConnectionCount
ConnectionCount == 0; 0; }}
}}

! .cctor in Disassembly

*ILLEGAL FOR NON-TRAINER USE**

Static constructors are used to initialize static fields. Static constructors are also
known as class constructors and type constructors. Static constructors are called
after a program begins running but before the first instance of the class is
created.
14 Module 6: Working with Types

The following example shows a DeviceConnection class that represents a

generic connection to a device. The class maintains a static field that holds the
current connection count. The static constructor is created with the same name
as the class but has the static attribute, rather than the public or private
attribute.
class DeviceConnection
{
public static uint ConnectionCount;
public void OpenConnection(string connectionName)
{
ConnectionCount++;
//Other work to open device
}
static DeviceConnection()
{
//Initialize static members
ConnectionCount = 0;
}
}

class MainClass
{
public static void Main()
{
// At some point before next line,
// static constructor is called
DeviceConnection d = new DeviceConnection();
d.OpenConnection("GameConsole:Joy1/3");
// Next line prints 1
Console.WriteLine(DeviceConnection.ConnectionCount);
}
}

A static constructor has no access modifiers, such as private or public. Inside a

static constructor, only static fields can be used. Instance fields must be
initialized in an instance constructor.
When the static constructor is viewed in disassembly, it has a different name,
.cctor, which stands for class constructor. In disassembly, instance constructors
are called .ctor. You can have both types of constructors in the same class.
Module 6: Working with Types 15

If you initialize a static field inline with a value, a static constructor is created
automatically. The following example shows how the DeviceConnection class
can be rewritten to use an implicit static constructor. The presence of the static
constructor can be verified by viewing the disassembly of the code.
class DeviceConnection
{
//Next line automatically creates static constructor
public static uint ConnectionCount = 0;
public void OpenConnection(string connectionName)
{
ConnectionCount++;
//Other work to open device
}
}

In the preceding example, the static field ConnectionCount is initialized inline

to a value of 0. When you initialize static fields inline, a static constructor is
implicitly created in which the initialization occurs. If you also provide an
explicit static constructor, the inline initialization is compiled into the explicit
static constructors. Inside the static constructor, the code for the inline
initializations runs first, and then the code that you wrote in the static
constructor runs.
16 Module 6: Working with Types

Private Constructors
Topic Objective
To explain when to use
private constructors. ! Prevent a Class from Being Instantiated
Lead-in ! Use Them on Classes with All Static Members
A private constructor can
never be called. Therefore ! Use a Protected Constructor to Inherit from the Class
any class with a private
constructor cannot be class
class Trig
Trig
instantiated. {{
public
public static
static double
double Sin
Sin (double
(double x)
x)
{{ //Calculate
//Calculate and return
and return sin(x)
sin(x) }}
public
public static
static double
double Cos
Cos (double
(double x)
x)
{{ //Calculate
//Calculate and return
and return cos(x)
cos(x) }}
public
public static
static double
double Tan
Tan (double
(double x)
x)
{{ //Calculate
//Calculate and
and return
return tan(x)
tan(x) }}
private
private Trig(){}
Trig(){}
}}

*ILLEGAL FOR NON-TRAINER USE**

A private constructor can never be called. Therefore any class with a private
constructor cannot be instantiated. The only type of class that uses a private
constructor is a class with all static members.
The following example shows how a private constructor is used to prevent a
class from being instantiated.
class Trig
{
public static double Sin (double x)
{
//Calculate and return sin(x)
}
public static double Cos (double x)
{
//Calculate and return cos(x)
}
public static double Tan (double x)
{
//Calculate and return tan(x)
}
private Trig(){}
}
Module 6: Working with Types 17

Classes with all static members can be used to maintain global algorithms, as
shown in the preceding example. They can also be used as a singleton class,
which has only one set of values and methods that is available while a program
is running.
To derive from a class with static members, you should mark the constructor as
protected. Marking the constructor as protected will prevent programmers from
creating instances of the class, but allow other classes to derive from it.

Note A class with static members is different than an interface. The static
members can contain implementations, a class can have static fields, but an
interface cannot.
18 Module 6: Working with Types

" Type Operations

Topic Objective
To provide an overview of
the topics covered in this
section. ! Conversions
Lead-in ! Casting
The .NET Framework
common language runtime ! Boxing
supports a variety of type
operations for working with
types.

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework common language runtime supports a variety of type
operations for working with types. This section discusses conversions and
conversion operators for determining and converting the type of an object. This
section also discusses how to cast types for conversion and for treating a type as
a different type. It also describes boxing and unboxing value types to treat them
as reference types.
Module 6: Working with Types 19

Conversions
Topic Objective
To explain when and how
to use explicit and implicit ! Explicit Conversions
conversions.
int
int xx == 5;
5;
Lead-in double
double yy == (double)
(double) x;
x;
Conversion is the process
of changing a type to ! Implicit Conversions
another type.
int
int xx == 5;
5;
double
double yy == x;
x;

! Conversion Operators
public
public static
static implicit
implicit operator
operator byte(Digit
byte(Digit d)
d)
public
public static
static explicit
explicit operator
operator Digit(byte
Digit(byte b)
b)

*ILLEGAL FOR NON-TRAINER USE**

Conversion is the process of changing a type to another type. Conversions are
necessary when a value of one type must be assigned to a variable of a different
type during assignment or when passing arguments to a method call.

Explicit and Implicit Conversions

In explicit conversions, you do not need to specify the name of the type in a cast
for assignment conversions or operand conversions.
The following example shows how to convert an int value to a double value by
using an explicit conversion.
public static bool BiggerThanFive(double value)
{
if (value > 5) return true;
else return false;
}
public static void Main()
{
int x = 5;
//Use an explicit conversion for assignment
double y = (double) x;
//Use an explicit conversion for operand
bool answer = BiggerThanFive((double) x);
}

The preceding example is an example of a widening conversion. The bit size of

an int is 32 bits, and the bit size of a double is 64 bits. Therefore, the type was
widened during the conversion.
20 Module 6: Working with Types

In implicit conversions, you do not need to specify the name of the type during
the conversion. Widening conversions can occur implicitly, and so they allow
for simpler syntax. The preceding example could be written more simply as
follows:
public static void Main()
{
int x = 5;
//Use an implicit conversion for assignment
double y = x;
//Use an implicit conversion for operand
bool answer = BiggerThanFive(x);
}

The following table shows the allowable implicit conversions for numeric types
in the common language runtime.
From To

sbyte short, int, long, float, double, or decimal

byte short , ushort, int, uint, long, ulong, float, double, or decimal
short int, long, float, double, or decimal
ushort int, uint, long, ulong, float, double, or decimal
int long, float, double, or decimal
uint long, ulong, float, double, or decimal
long float, double, or decimal
char ushort, int, uint, long, ulong, float, double, or decimal
float double
ulong float, double, or decimal

Some conversions can result in a loss of precision. For example, converting an

int to a float is an allowable implicit conversion, but a float has only seven
digits of precision. Depending on the value of the int, some digits of precision
may be lost.
The following example shows a narrowing conversion in which a double is
converted to an integer.
double y = 4.56;
int x = (int) y;

In this case, narrowing conversions must be explicit because there is almost

always a loss of precision in the value that is being converted. In the preceding
example, the value 4.56 will be truncated to 4 when it is assigned to x.
Module 6: Working with Types 21

Conversion Operators
You can create user-defined conversions by providing conversion operators in
your class or struct.
Use the following syntax for specifying a conversion operator:
public static [implicit | explicit] operator conv-type-out (conv-type-in
operand)
in which:
! conv-type-out is the name of the type to convert to.
! conv-type-in is the name of the type to convert from.
! operand is the name of the parameter holding the value being converted.

The following example shows how a structure that is called Digit, which
represents a value from 0 to 9, can convert implicitly to a byte and explicitly to
a Digit.
struct Digit
{
byte value;
public Digit(byte value)
{
if (value < 0 || value > 9)
throw new ArgumentException();
this.value = value;
}
public static implicit operator byte(Digit d)
{
//Implicitly convert from Digit to short
return d.value;
}
public static explicit operator Digit(byte b)
{
//Explicitly convert from short to Digit
return new Digit(b);
}
}
class MainClass
{
public static void Main()
{
Digit dig = new Digit(3);
byte b = dig; //Implicit conversion operator invoked
Console.WriteLine(b); //Prints 3
Digit dig2 = (Digit) b; //Explicit conversion invoked
Console.WriteLine(dig2); //Implicit conversion prints 3
}
}
22 Module 6: Working with Types

In the preceding example, the conversion from Digit to byte is implicit, while
the conversion from byte to Digit is explicit. You should use the following
guidelines to determine whether a conversion operator should be implicit or
explicit.
! A conversion operator should be implicit to make code easier to read.
Implicit conversions should never throw an error.
! A conversion operator should be explicit whenever information could be
lost in the conversion or if the conversion could throw an exception.
Module 6: Working with Types 23

Casting
Topic Objective
To explain how casting is
used in the .NET
Framework. ! Casting Up from Derived Class to Base Class
Lead-in ! Casting Down from Base Class to Derived Class
Casting is used for explicit
conversions. However, ! Type Operators
casting is also used for
changing the type that is # is
used to reference an object.
# as
# typeof
! Casting Interfaces

*ILLEGAL FOR NON-TRAINER USE**

Casting is used for explicit conversions. However, casting is also used for
changing the type that is used to reference an object.

Casting in an Inheritance Hierarchy

Casting on objects is frequently used to change the reference type of an object
to a base class reference or a derived class reference. When casting a derived
class to a base class, you do not need to explicitly cast the object. The following
example shows how a Shape type reference can be used to work with a Square
object.
//Shape is a base class
class Shape {...}
//Square is a derived class
class Square : Shape {...}

Square sq = new Square();

Shape sh = sq;
sh.ShapeMethod();

When casting from a base class to a derived class, you must explicitly cast the
object. If you cast to a derived type that does not match the underlying object,
an InvalidCastException error will be thrown.
24 Module 6: Working with Types

The following example shows how to cast from a base class type to a derived
class type.
Square sq = new Square();
Shape sh = sq;
Square sq2 = (Square) sh;//Cast down to Square
sh = new Shape();
sq2 = (Square) sh;//InvalidCastException

Type Operators
C# provides several operators to help cast object types appropriately. These
operators help you avoid InvalidCastException errors.
The is operator compares an object to a type. If the type matches the object,
true is returned. If the type does not match the object, false is returned.
Shape sh = new Shape();
Square sq;
if (sh is Square) sq = (Square) sh;

The as operator attempts to convert an object to a type. If the conversion is

successful, a reference of the specified type is assigned. Otherwise, null is
assigned.
Shape sh = new Shape();
Square sq = sh as Square;
if (sq == null)
Console.WriteLine("Shape was not a square");
else
Console.WriteLine("Shape was a square");

You can use the typeof operator for more advanced type operations. The typeof
operator will return a System.Type instance that describes the type through
reflection. If you have an instance of a class, you can call GetType to obtain the
same information.
For more information about reflection, the mechanism for obtaining
information about loaded assemblies and the types defined within them,
including classes, interfaces, and value types, see “Discovering Type
Information at Run time,” in the .NET Framework Software Developer’s Kit
(SDK) documentation and Module 17, “Attributes,” in Course 2349B,
Programming with the Microsoft .NET Framework (Microsoft Visual C#
.NET).

Casting Interfaces
Casting is also used to obtain interface references to an object. The following
example shows how the interface ICDPlayer can be obtained through casting
from the Device class, which implements the ICDPlayer interface.
ICDPlayer player;
Device d = new Device();
player = (ICDPlayer) d;//Cast to interface
player.Play();
Module 6: Working with Types 25

Boxing
Topic Objective
To explain when and how ! Boxing Occurs to Convert a Value Type to a
boxing occurs. Reference Type
Lead-in
Boxing and unboxing are # Instance of System.Object is allocated on heap
conversions that occur
automatically when a value
# Value type is copied to new object
type is converted to an int
int xx == 5;
5; //Value
//Value type
type
object or when an object is Object
Object o = x; //Boxed
o = x; //Boxed
converted to a value type. Console.WriteLine("The
Console.WriteLine("The answer
answer is
is :: {0}
{0} ",
", x);//Boxed
x);//Boxed
! Unboxing Occurs to Retrieve Value Type from Object
int
int yy == (int)
(int) o;
o; //unbox
//unbox
! Boxing Can Be Expensive If Inside Loops

*ILLEGAL FOR NON-TRAINER USE**

Boxing and unboxing are conversions that occur automatically when a value
type is converted to an object or when an object is converted to a value type.
Boxing and unboxing occur implicitly and can affect the performance of your
application code.

When Boxing Occurs

Boxing occurs when a value type must be converted to a reference type. Boxing
only occurs when converting to the type System.Object. Any other reference
type must have implicit or explicit conversion operators to convert from value
types.
The following example shows how an integer value type is converted to an
object reference type.
int x = 5; //Value type
Object o = x; //Implicit boxing operation occurs

In the preceding example, a boxing operation occurs when the object o is

assigned the value in x.
Boxing frequently occurs when calling methods that accept parameters of type
Object. For example, Console.WriteLine can accept a string and an object
parameter as follows.
int x = 5;
Console.WriteLine("The answer is: {0}",x);//Boxing occurs

In the preceding example, a boxing operation occurs on the call to

Console.WriteLine. Because Console.WriteLine requires an Object type as
the second parameter, x is implicitly boxed as an Object type.
26 Module 6: Working with Types

You can determine where boxing operations occur in your code by examining
the disassembly. For example, if you use the Microsoft intermediate language
(MSIL) Disassembler (Ildasm.exe), you will see an operation code called box,
which is followed by the type that is being boxed.

How Boxing Works

A value type must be copied from the stack to the heap if the value is going to
be treated as a reference type. The boxing operation allocates memory on the
heap for the value type and creates a reference to the new memory location.
Then it copies the value type into the new memory location.

Unboxing
To work with the value inside a boxed type, it must first be unboxed. Unboxing
a type will copy it from the heap into a variable on the stack.
The following example shows how to unbox an integer.
int x = 5;
Object o = x; //box
int y = (int) o; //unbox

If the underlying value type that is being unboxed is incompatible with the type
of the variable that it is assigned to, you will get an InvalidCastException.
int x = 5;
short s;
Object o = x; //box
s = (short) o; //Will throw InvalidCastException

Consequences
Boxing can cause performance problems if you do not minimize its occurrence.
The following example shows the consequences of boxing.
int age = 5;
int count = 1;
for (count = 1;count < 10;count++)
{
Console.WriteLine("Current Age = {0}",age);//1 Box
Console.WriteLine("Age in {0} year(s) will be {1}",
count, age+count);//2 box operations
}

In the preceding example, three boxing operations will occur for every iteration
through the loop. This kind of scenario can be very costly in terms of
performance. One solution is to box value types before entering a loop, as in the
following example.
int age = 5;
Object oAge = age; //1 box operation
int count = 1;
for (count = 1;count < 10;count++)
{
Console.WriteLine("Current Age = {0}",oAge);
Console.WriteLine("Age in {0} year(s) will be {1}",
count, age+count);//2 box operations
}
Module 6: Working with Types 27

In cases when the need for a higher level of performance is necessary, custom
classes can be created to encapsulate values and work with values as reference
types.
class RefInt32
{
public int Value;
public RefInt32(int value)
{
this.Value = value;
}
public override string ToString()
{
return Value.ToString();
}
public static implicit operator int (RefInt32 refInt)
{
return refInt.Value;
}
}

int age = 5;
RefInt32 refAge = new RefInt32(age); //Convert to ref type
int count = 1;
RefInt32 refCount = new RefInt32(count); //Convert to ref type
RefInt32 refTotal = new RefInt32(0);
for (refCount.Value = 1;refCount.Value < 10;refCount.Value++)
{
refTotal.Value = refAge.Value + refCount.Value;
Console.WriteLine("Current Age = {0}",refAge);
Console.WriteLine("Age in {0} year(s) will be {1}",
refCount,refTotal);//0 box operations
}

The preceding example demonstrates the importance of overriding appropriate

Object methods to get expected behavior. If the recipient of your reference type
calls one of the methods that are expecting appropriate behavior, it may cause
problems. In the preceding example, you must override ToString.
28 Module 6: Working with Types

" Interfaces
Topic Objective
To provide an overview of
the topics covered in this
section. ! Inheritance Considerations
Lead-in ! Explicit Interface Implementation
When designing and using
interfaces, you should
consider a number of
factors.

*ILLEGAL FOR NON-TRAINER USE**

When designing and using interfaces, you should consider a number of factors.
This section discusses how multiple inheritance works through interfaces. This
section also explains how to explicitly implement interfaces.
Module 6: Working with Types 29

Inheritance Considerations
Topic Objective
To explain the use of
inheritance and the use of
interfaces. ! Multiple Inheritance
Lead-in interface
interface IFoo
IFoo {void
{void DoSomething1();}
DoSomething1();}
Interfaces are used only interface
interface IBar
IBar {void
{void DoSomething2();}
DoSomething2();}
through inheritance. class
class MyObject
MyObject :: IFoo,
IFoo, IBar
IBar {...}
{...}
! Deriving New Interfaces from Existing Ones

interface
interface INewInterface
INewInterface :: IFoo,
IFoo, IBar
IBar
{void DoSomething3();}
{void DoSomething3();}

! Base Class Interfaces

*ILLEGAL FOR NON-TRAINER USE**

Interfaces are used only through inheritance. There are several ways to group or
partition functionality when you are using interfaces. You can use multiple
inheritance to combine functionality from multiple interfaces. Interfaces also
can inherit from other interfaces, allowing functionality to be partitioned into
multiple groups.

Multiple Inheritance
In the .NET Framework common language runtime, a class must inherit from
only one class. However, a class can inherit from zero or more interfaces in
addition to inheriting from one class. Interfaces are the only type to allow
multiple inheritance in the common language runtime. The following example
shows how a class can inherit from two interfaces.
interface IFoo
{
void DoSomething1();
}
interface IBar
{
void DoSomething2();
}
class MyObject : IFoo, IBar
{
public void DoSomething1()
{
Console.WriteLine("DoSomething1 called");
}
public void DoSomething2()
{
Console.WriteLine("DoSomething2 called");
}
}
30 Module 6: Working with Types

Multiple inheritance is an important design consideration when you are

choosing between abstract classes and interfaces. If two sets of functionality are
designed into two abstract classes, a single class cannot inherit from both
classes. However, if interfaces are used, a single class can inherit from both
interfaces. If a specification of functions, properties, or events is likely to be
used by many different kinds of classes, you should use an interface instead of
an abstract class.

Deriving New Interfaces from Existing Ones

You can also create new interfaces by deriving from other interfaces. The
following example shows how a new interface that is called INewInterface is
created from the IFoo and IBar interfaces.
interface IFoo
{
void DoSomething1();
}
interface IBar
{
void DoSomething2();
}
interface INewInterface : IFoo, IBar
{
void DoSomething3();
}
class MyObject : INewInterface
{
public void DoSomething1()
{
Console.WriteLine("DoSomething1 called");
}
public void DoSomething2()
{
Console.WriteLine("DoSomething2 called");
}
public void DoSomething3()
{
Console.WriteLine("DoSomething3 called");
}
}
Module 6: Working with Types 31

Base Class Interfaces

If you derive a new class from a base class that implements an interface, you
must decide if the derived class will also implement the interface. When an
instance of the derived class is converted to the interface, the inheritance
hierarchy is searched until a class that implements the interface is found. Then
the interface methods are called on that class.
The following example shows what happens when interface methods are called
on a derived class that does not implement the interface.
interface IFoo
{
void DoSomething1();
}
class Base : IFoo
{
public void DoSomething1()
{
Console.WriteLine("Base DoSomething1 called");
}
}
class Derived : Base
{
public new void DoSomething1()
{
Console.WriteLine("Derived DoSomething1 called");
}
}
class MainClass
{
public static void Main()
{
Derived d = new Derived();
IFoo i = (IFoo) d;
d.DoSomething1();
i.DoSomething1();
}
}

This code generates the following output:

Derived DoSomething1 called
Base DoSomething1 called

In the preceding example, the base class DoSomething1 method is called when
an IFoo variable is used. If this behavior is not the desired behavior, then the
derived class must be modified to also inherit from the IFoo interface. Then,
the derived class DoSomething1 method will be called when the IFoo variable
is used.
32 Module 6: Working with Types

Explicit Interface Implementation

Topic Objective ! Class vs. Interface Accessibility
To distinguish class
accessibility and interface ! Use Explicit Interface Implementation
accessibility, and to explain
when to use explicit # When interface member names that are combined with
interface implementation. class names are confusing
Lead-in # When inheriting from multiple interfaces with same
When you implement an
members
interface in a class, the
interface methods are interface
interface IFoo
IFoo {void
{void DoSomething();}
DoSomething();}
exposed through the interface
interface IBar {void DoSomething();}
IBar {void DoSomething();}
interface type, and the class class
class MyObject
MyObject :: IFoo,
IFoo, IBar
IBar {{
type. void IFoo.DoSomething()
void IFoo.DoSomething()
{Console.WriteLine("IFoo
{Console.WriteLine("IFoo DoSomething
DoSomething called");}
called");}
void
void IBar.DoSomething()
IBar.DoSomething()
{Console.WriteLine("IBar
{Console.WriteLine("IBar DoSomething
DoSomething called");}
called");}
}}

*ILLEGAL FOR NON-TRAINER USE**

When you implement an interface in a class, the interface methods are exposed
through the interface type and the class type.
The following example shows how an interface method can be called by both
the class type and the interface type.
interface IFoo
{
void DoSomething();
}
class MyObject : IFoo
{
public void DoSomething()
{
Console.WriteLine("DoSomething called");
}
}
class MainClass
{
public static void Main()
{
MyObject o = new MyObject();
//Call method through class type
o.DoSomething();
IFoo foo = (IFoo) o;
//Call method through interface type
foo.DoSomething();
}
}
Module 6: Working with Types 33

You can use explicit interface implementation to prevent the class type from
accessing the method. This technique is useful if the interface member names
are likely to confuse a user of the class. Also, explicit interface implementation
is mandatory if you inherit from multiple interfaces that have the same
members.
To use explicit interface implementation, you prepend the name of the interface
to the name of the member in your class definition. You should not use any
access modifiers in the member definition. Access modifiers are not allowed
because the explicit interface implementation is only accessible through the
interface type.
The following example shows how explicit interface implementation can avoid
conflicts between multiple interfaces with the same members.
interface IFoo
{
void DoSomething();
}
interface IBar
{
void DoSomething();
}

class MyObject : IFoo, IBar

{
void IFoo.DoSomething()
{
Console.WriteLine("IFoo DoSomething called");
}
void IBar.DoSomething()
{
Console.WriteLine("IBar DoSomething called");
}
}

class MainClass
{
public static void Main()
{
MyObject o = new MyObject();
IFoo foo = (IFoo) o;
IBar bar = (IBar) o;
foo.DoSomething();
bar.DoSomething();
}
}

This code generates the following output:

IFoo DoSomething called
IBar DoSomething called
34 Module 6: Working with Types

" Managing External Types

Topic Objective
To provide an overview of
the topics covered in this
section. ! Platform Invocation Services
Lead-in ! COM Interoperability
The .NET Framework
common language runtime
is not an isolated system.
Most programs will require
some level of interaction
with outside applications.

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework common language runtime is not an isolated system.
Most programs will require some level of interaction with outside applications.
The common language runtime provides Platform Invocation Services for
interacting with code in DLLs. Also, the common language runtime provides
integration services to interact with COM objects.

Warning Using unmanaged external types is risky because the common

language runtime cannot enforce security, manage memory, or provide code
type safety verification checking for unmanaged code.

This module does not cover all aspects of Platform Invocation Services or COM
Integration Services. For more information, see Module 15, “Interoperating
Between Managed and Unmanaged Code,” in Course 2349B, Programming
with the Microsoft .NET Framework (Microsoft Visual C# .NET) and
“Interoperating with Unmanaged Code” in the .NET Framework SDK
documentation.
Module 6: Working with Types 35

Platform Invocation Services

Topic Objective
To introduce the use of
Platform Invocation Services
to call external functions. ! Also Known as PInvoke
Lead-in ! Use DllImport Attribute to Import an API Function from
Platform Invocation an External DLL
Services, also known as
PInvoke, allow managed [DllImport("user32.dll",
[DllImport("user32.dll", CharSet=CharSet.Ansi)]
CharSet=CharSet.Ansi)]
code to interact with public
public static
static extern
extern int
int MessageBox(int
MessageBox(int h,
h, string
string m,
m,
unmanaged code in existing string
string c,
c, int
int type);
type);
DLLs.
public
public static
static void
void Main()
Main()
{{ string
string pText == "Hello
pText "Hello World!";
World!";
string
string pCaption
pCaption == "PInvoke
"PInvoke Test";
Test";
MessageBox(0,
MessageBox(0, pText,
pText, pCaption,
pCaption, 0);
0); }}

*ILLEGAL FOR NON-TRAINER USE**

Platform Invocation Services, also known as PInvoke, allow managed code to
interact with unmanaged code in existing DLLs. PInvoke provides the code that
is needed to locate and invoke a function and to marshal parameters to and from
the function.
To call an external function, you use the DllImport attribute to provide the
name of the DLL and any other characteristics, such as the use of ANSI or
Unicode strings by the DLL. After the function has been declared, you can call
it from managed code.
The following example shows how to call the MessageBox API located in
User32.dll.
using System;
using System.Runtime.InteropServices;

class MainClass
{
[DllImport("user32.dll", CharSet=CharSet.Ansi)]
public static extern int MessageBox(int h, string m,
string c, int type);

public static void Main()

{
string pText = "Hello World!";
string pCaption = "PInvoke Test";
MessageBox(0, pText, pCaption, 0);
}
}

For more information on PInvoke, see Module 15, “Interoperating Between

Managed and Unmanaged Code,” in Course 2349B, Programming with the
Microsoft .NET Framework (Microsoft Visual C# .NET) and “Interoperating
with Unmanaged Code” in the .NET Framework SDK documentation.
36 Module 6: Working with Types

COM Interoperability
Topic Objective
To introduce COM
interoperability.
! Exposing .NET Framework Classes to COM
Lead-in
COM interoperability allows # Must create COM Callable Wrapper
managed code to create
and call COM objects. It # Create CCWs by using Tlbexp.exe
also allows COM objects to
create and call .NET # Register by using Regasm.exe
Framework objects.
! Exposing COM Classes to the .NET Framework
# Must create Runtime Callable Wrapper
# Create RCWs by using Tlbimp.exe

*ILLEGAL FOR NON-TRAINER USE**

COM interoperability allows managed code to create and call COM objects. It
also allows COM objects to create and call .NET Framework objects.

Exposing .NET Framework Classes to COM

You can expose .NET Framework classes to COM by creating COM callable
wrappers (CCW) for each .NET Framework class in your application. The
CCW creates and manages standard COM elements, such as IUknown and
other standard interfaces, GUIDs, IIDs, and reference counting. These elements
allow COM objects to interoperate with your .NET Framework classes as if the
.NET Framework classes were real COM classes.
The .NET Framework classes that you write do not need to be aware of any
COM elements. However, you can directly control some COM elements when
necessary, by such means as specifying manual IIDs for your interfaces.
You can create CCWs for your .NET Framework classes by running the Type
Library Exporter (Tlbexp.exe). You can also register your .NET Framework
classes as COM classes by using the Assembly Registration Tool (Regasm.exe).
Module 6: Working with Types 37

Exposing COM Classes to the .NET Framework

Managed code can also create and call existing COM objects. You can
accomplish this by creating a runtime callable wrapper (RCW) for each COM
class that you want to access from managed code. Similar to the CCW, the
RCW handles COM specific semantics, such as reference counting,
QueryInterface for different IIDs, and marshaling. Your managed code can
use COM interfaces as if they were managed interfaces and COM classes as if
they were managed classes.
You can create RCWs by using the Type Library Importer (Tlbimp.exe).
For more information on COM Interopability, see Module 15, “Interoperating
Between Managed and Unmanaged Code,” in Course 2349B, Programming
with the Microsoft .NET Framework (Microsoft Visual C# .NET) and
“Interoperating with Unmanaged Code” in the .NET Framework SDK
documentation.
38 Module 6: Working with Types

Lab 6: Working with Types

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will create a
class that overrides
methods in System.Object.
You will also create an
interface that must be
implemented explicitly.

*ILLEGAL FOR NON-TRAINER USE**

Objectives
After completing this lab, you will be able to:
! Create classes that override the GetHashCode, and equality methods and
operators.
! Create classes that provide conversion operators.
! Implement an explicit interface in a class and use it from a client.

Lab Setup
Starter and solution files are associated with this lab. The starter files are in the
folder <install folder>\Labs\Lab06\Starter, and the solution files are in the
folder <install folder>\Labs\Lab06\Solution.

Estimated time to complete this lab: 45 minutes

Module 6: Working with Types 39

Exercise 1
Overriding System.Object Methods
In this exercise, you will create a structure that represents an office in a
building. The Office structure stores the size, building number, and room
number of an office. You will override appropriate methods and operators to
support retrieving hash codes and comparing different offices.
You will also create a structure called OfficeUnit that is similar to the Office
structure. The only difference between the OfficeUnit structure and the Office
structure is that OfficeUnit represents size as an enumerated type with the
values small, medium, or large. The Office structure represents size as square
footage. You will write an explicit conversion operator to convert values of
type Office to type OfficeUnit.

! Implement a hash code

1. Open the Offices project located in the <install folder>\Labs\
Lab06\Starter\Offices folder.
2. Open the Office.cs file.
3. Locate the Office structure.
4. Override the GetHashCode method. Generate and return a hash code by
using the following algorithm:
HashCode = Building * 10000 + Room

! Provide a string representation

1. Override the ToString method.
2. Generate and return a string that contains the building number, followed by
a forward slash, followed by the room number. You can use the following
code to build and return the string.
return String.Concat(Building,"/",Room);

! Implement equality
1. Override the Equals method.
2. Cast the object parameter to type Office.
3. Compare the size, room, and building numbers of the parameter to this. If
the values are all equal, return true. If they are not equal, return false.
4. Override the == and != operators. Implement them by calling the Equals
method.
40 Module 6: Working with Types

! Implement conversion
1. Define an explicit conversion operator to convert from type Office to
OfficeUnit.
2. Convert the size from square footage to an OfficeSizes value according to
the following table. The OfficeSizes enumeration is already defined in the
start code for you.
Square Footage OfficeSizes

<= 64 Small
>64 and <100 Medium
>=100 Large

3. Assign the Building and Room values to the new type and return an
instance of the new type.

! Test
1. Open the Main.cs file.
2. Create two offices called o1 and o2. Assign different sizes, room numbers,
and building numbers to each office variable.
3. Use the == operator to compare the two offices. Print the results to the
console.
4. Call GetHashCode on both offices and print the results.
5. Call ToString on both offices and print the results.
6. Create an OfficeUnit and assign it one of the offices. Use explicit
conversion to assign the office.
7. Print all of the values of the OfficeUnit.
8. Compile and run the program.
The two offices should not be equal. They should have different hash codes.
The ToString method should print the building and room numbers, not the
class names. Finally, the printed enumerated size should match the square
footage appropriately.
Module 6: Working with Types 41

Exercise 2
Implementing an Explicit Interface
In this exercise, you will create an interface called IRange, which provides
properties and methods to select and print a range. You will also modify a class
called TextEntry to inherit from IRange. This combination allows text in the
TextEntry class to be selected as a range and printed.
The TextEntry class already implements a Print method. Because the IRange
interface also has a Print method, you will need to explicitly implement
IRange in the TextEntry class to avoid a name conflict.

! Create an explicit interface

1. Open the Interfaces project located in the <install folder>\Labs\
Lab06\Starter\Interfaces folder.
2. Open the TextEntry.cs file.
3. Define an interface called IRange that has the following properties.
Property Name Type

RangeBegin uint
RangeEnd uint

4. Define the following methods for IRange.

Method Name Return Type Parameters

Select void uint rb, uint re

Print void none

5. Modify the TextEntry class to inherit from IRange.

6. In the TextEntry class, create private fields named rangeBegin and
rangeEnd to store the RangeBegin and RangeEnd data values. Use the
uint type for both fields.
7. Implement the IRange RangeBegin property.
a. Implement the get accessor by returning the value of rangeBegin.
b. Implement the set accessor by storing the value in rangeBegin. Check to
ensure that the new value is less than the length of the text field, and that
the value of rangeEnd is not less than rangeBegin.
8. Implement the IRange RangeEnd property.
a. Implement the get accessor by returning the value of rangeEnd.
b. Implement the set accessor by storing the value in rangeEnd. Check to
ensure that the new value does not exceed the length of the text field,
and that the value of rangeEnd is not less than rangeBegin.
9. Implement the IRange Select method. Ensure that the re parameter is not
less than the rb parameter, and that the new values are not greater than the
length of the text field. Assign rb to rangeBegin and re to rangeEnd.
10. Implement the IRange Print method. Using the rangeBegin and rangeEnd
fields, create a text range from the text field by using the SubString
method. Then print the resulting string to the console.
42 Module 6: Working with Types

! Use the interface

1. Open the Main.cs file.
2. In the MainClass class, create an instance of the TextEntry class called
myEntry.
3. Create an interface of type IRange named r and cast myEntry to r.
4. Initialize the Text property on myEntry with a value, such as “The quick
brown fox jumped over the gate.”
5. Select a range by using the interface variable r. For example, the values 4
and 10 will select the word “quick.”
6. Call the Print method on myEntry.
7. Call the Print method on r.
8. Compile and run the program. You should see the entire Text property
printed to the console, followed by the range of text you selected.
Module 6: Working with Types 43

Review
Topic Objective
To reinforce module
objectives by reviewing
key points. ! System.Object Class Functionality
Lead-in ! Specialized Constructors
The review questions cover
some of the key concepts ! Type Operations
taught in the module.
! Interfaces
! Managing External Types

*ILLEGAL FOR NON-TRAINER USE**

1. What kind of algorithm should you use to implement the GetHashCode
method?
The algorithm should be efficient and return a unique number.

2. What is the default behavior of the ToString method?

The default behavior of the ToString method is to return the name of
the class.

3. How can you determine if two separate object references are the same
object?
Use the ReferenceEquals method to compare the two references.

4. If you override the Equals method, what else should you override?
You should override the == and != operators.

5. When should you use a private constructor?

Use a private constructor to prevent a class from being instantiated. An
example of such a class is a singleton class with static methods and
fields.
44 Module 6: Working with Types

6. When should you use implicit conversions, and when should you use
explicit conversions?
Use implicit conversions for improved readability and use. Use explicit
conversions when the conversion could cause a loss of data or throw an
exception.

7. When do boxing operations occur?

Boxing occurs when a value type is converted to an Object type.
Unboxing occurs when the value is retrieved from an Object type.

8. How do you explicitly implement an interface?

Do not use the public access modifier. Use the name of the interface in
front of the field or method names. For example, void
IFoo.DoSomething().
Module 7: Strings,
Arrays, and Collections

Contents

Overview 1
Strings 2
Terminology – Collections 20
.NET Framework Arrays 21
.NET Framework Collections 39
Lab 7: Working with Strings, Enumerators,
and Collections 57
Review 63
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, place or event is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

 2001-2002 Microsoft Corporation. All rights reserved.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Module 7: Strings, Arrays, and Collections iii

Instructor Notes
Presentation: After completing this module, students will be able to:
120 Minutes
! Parse, format, manipulate, and compare strings.
Lab: ! Use the classes in the System.Array and System.Collections namespaces.
60 Minutes
! Improve the type safety and performance of collections by using specialized
collections and class-specific code.

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach
this module.

Required Materials
To teach this module, you need the Microsoft® PowerPoint® file 2349B_07.ppt.

Preparation Tasks
To prepare for this module, you should:
! Read all of the materials for this module.
! Practice the demonstrations.
! Complete the lab.
iv Module 7: Strings, Arrays, and Collections

Demonstrations
This section provides demonstration procedures that will not fit in the margin
notes or are not appropriate for the student notes.

Sorting and Enumerating an Array

In this demonstration, you will show students how to sort and enumerate an
array.
The code for this demonstration is contained in one project and is located in
<install folder>\Democode\Mod07\Demo07.1. In addition, the code for the
individual demonstration is provided in the student notes.

ArrayList
In this demonstration, you will show students how ArrayList implements the
IList interface by using an array whose size is dynamically increased as
required.
The code for this demonstration is contained in one project and is located in
<install folder>\Democode\Mod07\Demo07.2. In addition, the code for the
individual demonstration is provided in the student notes.

Hashtable
In this demonstration, you will show students how to create a hash table that is
used for searches.
The code for this demonstration is contained in one project and is located in
<install folder>\Democode\Mod07\Demo07.3. In addition, the code for the
individual demonstration is provided in the student notes.
In all of the preceding demonstrations, use the debugger to step through the
code while you point out features.
Module 7: Strings, Arrays, and Collections v

Module Strategy
Use the following strategy to present this module:
! Strings
Discuss how to work with strings in the Microsoft .NET Framework,
including common operations, such as parsing, formatting, manipulating,
and comparing strings.
! Terminology – Collections
Define the term collection as it is used in this module and identify where
collections are found in the .NET Framework. Be sure that students
understand that the term collection is used in its broader sense: to describe a
group of items.
! .NET Framework Arrays
Introduce the System.Array class as the base class of all array types that
contains methods for creating, manipulating, searching, and sorting arrays.
Discuss features of arrays that are specific to C#. Explain the role of the
IEnumerable and IEnumerator interfaces in System.Array and
System.Collections classes.
Use the Sorting and Enumerating an Array demonstration to show how to
sort and enumerate an array.
! .NET Framework Collections
Briefly introduce some commonly used classes in the System.Collections
namespace.
Discuss the IList interface with regards to classes that represent an ordered
collection of objects that can be individually indexed. Use the ArrayList
demonstration to reinforce this concept.
Discuss the IDictionary interface and the classes that it implements. Use
the Hashtable demonstration to show how to use the IDictionary interface.
Provide guidelines to help students distinguish between collections and
arrays, and explain when collections are used.
Discuss runtime casting for type safety and the effects of runtime casting,
and boxing and unboxing on performance. Discuss techniques for handling
boxing and unboxing to optimize performance.
Module 7: Strings, Arrays, and Collections 1

Overview
Topic Objective
To provide an overview of
the module topics and
objectives.
! Strings
Lead-in ! Terminology – Collections
In this module, you will learn
about some of the key ! .NET Framework Arrays
classes in the .NET
Framework class library. ! .NET Framework Collections

*ILLEGAL FOR NON-TRAINER USE**

In this module, you will learn about some of the key classes in the Microsoft®
.NET Framework class library. Specifically, you will learn how to work with
strings, arrays, collections, and enumerators.
After completing this module, you will be able to:
! Parse, format, manipulate, and compare strings.
! Use the classes in the System.Array and System.Collections namespaces.
! Improve the type safety and performance of collections by using specialized
collections and class-specific code.
2 Module 7: Strings, Arrays, and Collections

" Strings
Topic Objective
To introduce the topics in
the section. ! Parse

Lead-in ! Format
In this section, you will learn ! Format Examples
how to work with strings in
! Changing Case
the .NET Framework.
! Compare
! Trim and Pad
! Split and Join
! StringBuilder
! C# Specifics
! Regular Expressions

*ILLEGAL FOR NON-TRAINER USE**

In the C# language, string is an alias for System.String in the .NET
Framework. The System.String type represents a string of Unicode characters.
Working with strings is an everyday task in software development, and includes
operations, such as parsing, formatting, manipulating, and comparing strings.
The String object is immutable. Therefore, every time you use one of the
methods in the System.String class, you create a new string object. When you
want to perform repeated modifications to a string, the overhead that is
associated with creating a new String object can be costly. As an alternative,
you can use the System.Text.StringBuilder class to modify a string without
creating a new object.
In this section, you will learn how to work with strings in the .NET Framework.
Module 7: Strings, Arrays, and Collections 3

Parse
Topic Objective ! Parse Method Converts a Numeric String to a Numeric
To explain how the Parse
method is used to convert
string
string MyString
MyString == "12345";
"12345";
numeric strings to a .NET
int
int MyInt == int.Parse(MyString);
MyInt int.Parse(MyString);
Framework numeric base
type. MyInt++;
MyInt++;
Console.WriteLine(MyInt);
Console.WriteLine(MyInt);
Lead-in //
// The
The output
output to
to the
the console
console is
is "12346".
"12346".
The Parse method converts
a string that represents a
.NET Framework numeric ! To Ignore Commas, Use the
base type to an actual .NET NumberStyles.AllowThousands Flag
Framework numeric base
type. string
string MyString
MyString == "123,456";
"123,456";
int
int MyInt == int.Parse(MyString,
MyInt int.Parse(MyString,
System.Globalization.NumberStyles.AllowThousands);
System.Globalization.NumberStyles.AllowThousands);
Console.WriteLine(MyInt);
Console.WriteLine(MyInt);
//
// The
The output
output to
to the
the console
console is
is "123456".
"123456".

*ILLEGAL FOR NON-TRAINER USE**

The Parse method converts a string that represents a .NET Framework numeric
base type to an actual .NET Framework numeric base type.
The Parse method takes a combination of up to three parameters, as follows:
! The string to be converted
! One or more values from the System.Globalization.NumberStyles
enumeration
! A NumberFormatInfo class

Because the Parse method assumes that all string input represents a base-10
value, non-base-10 values are not parsable. The Parse method also does not
parse strings that represent the values NaN (Not A Number), PositiveInfinity,
or NegativeInfinity of the Single and Double classes because they are not real
numbers.
The following code example converts a string to an int value, increments that
value, and displays the result:
string MyString = "12345";
int MyInt = int.Parse(MyString);
MyInt++;
Console.WriteLine(MyInt);
// The output to the console is "12346".
4 Module 7: Strings, Arrays, and Collections

Handling Nonnumeric Characters

The NumberStyles enumeration is useful if you have a string that contains
nonnumeric characters that you want to convert into a .NET Framework
numeric base type. You must use this enumeration to parse a string with a
currency symbol, decimal point, exponent, parentheses, and so on.
For example, a string that contains a comma cannot be converted to an int
value by using the Parse method unless you pass the
System.Globalization.NumberStyles enumeration.

Incorrect Way to Parse a String with Nonnumeric Characters

The following code example is invalid and raises an exception. It illustrates the
incorrect way to parse a string that contains nonnumeric characters.
string MyString = "123,456";
// the following line raises a System.Format exception
int MyInt = int.Parse(MyString);
Console.WriteLine(MyInt);

Correct Way to Parse a String with Nonnumeric Characters

When you apply the System.Globalization.NumberStyles enumeration with
the AllowThousands flag, the Parse method ignores the comma that raised the
exception in the preceding example.
The following code example uses the same string as the preceding example but
does not raise an exception.
string MyString = "123,456";
int MyInt = int.Parse(MyString,
System.Globalization.NumberStyles.AllowThousands);
Console.WriteLine(MyInt);
// The output to the console is "123456"
Module 7: Strings, Arrays, and Collections 5

Format
Topic Objective
To explain how to use
format strings, or specifiers, ! Format Strings Are Used in Methods That Create String
to format the appearance of Representations of a .NET Framework Data Type
your application.
# To display $100.00 to the console on computers on
Lead-in which U.S. English is the current culture
The .NET Framework
provides several format int
int MyInt
MyInt == 100;
100;
strings that you can use to string
format the appearance of string MyString
MyString == MyInt.ToString("C");
MyInt.ToString("C");
Console.WriteLine(MyString);
Console.WriteLine(MyString);
strings that derive from
other objects. # Alternatively
int
int MyInt
MyInt == 100;
100;
Console.WriteLine("{0:C}",
Console.WriteLine("{0:C}", MyInt);
MyInt);

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework provides several format strings, or specifiers, that you
can use to format the appearance of strings that derive from other objects.
There are several advantages to converting base data types to strings before
displaying them to users. Strings are easily displayed and can be appended to
the messages and dialog boxes of your application. You can also use format
specifiers to display the same numeric value in scientific format, monetary
format, hexadecimal format, and so on.

When to Use Format Strings

You can use format specifiers in situations where your application stores
information in a format that is designed for use by the application, and not by
the user. For example, a business application may keep track of the current date
and time in a DateTime object to log when transactions are completed. The
DateTime object stores information in which the user is not necessarily
interested, such as the number of milliseconds that have elapsed since the
creation of the object.
You can also use format specifiers to display only information that is of interest
to the user, such as the date and hour of the transaction. Additionally, you can
dynamically modify strings that are created by using format specifiers to
represent monetary, date, and time conventions for the current culture. For
example, your application can display the date and time in the notation that is
specific to the user’s current culture.
6 Module 7: Strings, Arrays, and Collections

Methods Used with Format Strings

Format strings are used with any method that creates a string representation of a
.NET Framework data type, such as Int32, Int64, Single, Double,
Enumeration, DateTime, and so on. Format strings are also used with
Console.Writeline, String.Format, and several methods in the System.IO
namespace.
Additionally, every base data type contains a ToString method that returns a
string representation of the data type’s value and accepts a string format
specifier. You can control the layout and design of strings that are created by
any of these methods by using one of several format strings defined by the
.NET Framework.

Using the ToString Method

The ToString method is useful if you want to convert one of the standard .NET
Framework data types to a string that represents that type in some other format.
For example, if you have an integer value of 100 that you want to represent to
the user as a currency value, you can easily use the ToString method and the
currency format string ("C") to produce a string of "$100.00". The original
value that is contained in the data type is not converted, but a new string is
returned that represents the resulting value. This new string cannot be used for
calculation until it is converted back to a .NET base data type. The original
value, however, can be calculated at any time.

Note Computers that do not have U.S. English specified as the current culture
will display whatever currency notation is used by the current culture.

In the following code example, the ToString method displays the value of 100
as a currency-formatted string in a console window:
int MyInt = 100;
string MyString = MyInt.ToString("C");
Console.WriteLine(MyString);

The preceding code displays $100.00 to the console on a computer on which

U.S. English is the current culture.

Using Console.Writeline
The Console.WriteLine method also accepts a format string specifier as an
argument and can produce the same value as the preceding example.
Console.Writeline accepts string format specifiers in the form, where the
characters inside the curly brackets specify the formatting to apply to the
variable.
The following code example uses the Console.WriteLine method to format the
value of MyInt to a currency value.
int MyInt = 100;
Console.WriteLine("{0:C}", MyInt);

In the preceding example, the 0 character specifies the variable or value on

which to apply formatting. In this example, it is the first and only variable. The
characters that follow the colon are interpreted as string format specifiers.
Module 7: Strings, Arrays, and Collections 7

Format Examples
Topic Objective
To provide examples of ! Currency Format
format strings that return
common numeric string # C - $XX,XXX.XX
types.
int
int MyInt
MyInt == 12345;
12345;
Lead-in string
string MyString
MyString == MyInt.ToString("C"
MyInt.ToString("C" ););
Let’s look at some examples //
// In
In the
the U.S.
U.S. English
English culture:
culture: "$12,345.00"
"$12,345.00"
of format strings that return
the value of MyString in the ! Date Time Format
currency and date time
formats. # D - dd MMMM yyyy
# d - MM/dd/yyyy
DateTime
DateTime MyDate
MyDate == new
new DateTime(2000,
DateTime(2000, 1,
1, 10,
10, 0,
0, 0,
0, 0);
0);
string
string MyString
MyString == MyDate.ToString(
MyDate.ToString( "d"
"d" );
);
//
// In
In the
the U.S.
U.S. English
English culture:
culture: "1/10/2000"
"1/10/2000"

*ILLEGAL FOR NON-TRAINER USE**

The standard numeric, picture numeric, date and time, and enumeration format
strings are described in detail in the .NET Framework Software Development
Kit (SDK). This topic provides examples of these format strings.
The following examples show the use of the format string that returns the value
of MyInt in the currency format:
int MyInt = 12345;

string MyString = MyInt.ToString( "C" );

// In the U.S. English culture, MyString has the value:
// "$12,345.00".

The following table lists some format characters for standard patterns that are
used to format DateTime types.
Associated Example Format Pattern
Format Character Property/Description (en-US)

d ShortDate Pattern MM/dd/yyyy

D LongDatePattern Dd MMMM yyyy
f Full date and time (long date Dd MMMM yyyy
and short time) HH:mm
F FullDateTimePattern (long Dd MMMM yyyy
date and long time) HH:mm:ss
8 Module 7: Strings, Arrays, and Collections

The following example shows the use of the format string that returns the value
of MyDate in the short date pattern format:
DateTime MyDate = new DateTime(2000, 1, 10, 0, 0, 0);

string MyString = MyDate.ToString( "d" );

// In the U.S. English culture, MyString has the value:
// "1/10/2000".
Module 7: Strings, Arrays, and Collections 9

Changing Case
Topic Objective
To explain how to use the
String.ToUpper and
String.ToLower methods to
! You Can Easily Change the Case of a String
change the case of a string. # String.ToUpper – converts to upper case
Lead-in
string
string MyString
MyString == "hello
"hello world!";
world!";
You can easily change the
//
// outputs:
outputs: HELLO
HELLO WORLD!
WORLD!
case of a string by using the
Console.WriteLine(MyString.ToUpper());
Console.WriteLine(MyString.ToUpper());
String.ToUpper and
String.ToLower methods.
# String.ToLower – converts to lower case
string
string MyString
MyString == "HELLO
"HELLO WORLD!";
WORLD!";
// outputs: hello world!
// outputs: hello world!
Console.WriteLine(MyString.ToLower());
Console.WriteLine(MyString.ToLower());

*ILLEGAL FOR NON-TRAINER USE**

You can easily change the case of a string by using the two methods that are
described in the following table.
Method Name Use

String.ToUpper Converts all characters in a string to uppercase.

String.ToLower Converts all characters in a string to lowercase.

String.ToUpper and String.ToLower provide an override that accepts a

culture.
The String.ToUpper method changes all of the characters in a string to
uppercase.
The following code example converts the string "hello world!" from
lowercase to uppercase:
string MyString = "hello world!";
Console.WriteLine(MyString.ToUpper());

The preceding example displays HELLO WORLD! to the console.

The String.ToLower method is similar to the String.ToUpper method, but it
converts all of the characters in a string to lowercase.
The following code example converts the string "HELLO WORLD!" to lowercase.
string MyString = "HELLO WORLD!";
Console.WriteLine(MyString.ToLower());

The preceding example displays hello world! to the console.

10 Module 7: Strings, Arrays, and Collections

Compare
Topic Objective
To introduce some of the
value-comparison methods ! The .NET Framework Has Methods to Compare Strings
that are used to compare
the values of strings. # For example, the Compare method compares the
Lead-in current string object to another string or object, returning:
The .NET Framework - Negative if first string is less than second string
provides several value-
comparison methods to
- 0 if the two strings are equal
compare the values of - Positive if first string is greater than second string
strings.
string
string MyString
MyString == "Hello
"Hello World!";
World!";
Console.WriteLine(
Console.WriteLine(
String.Compare(MyString,"Hello
String.Compare(MyString,"Hello World!"));
World!"));
//
// outputs:
outputs: 00

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework provides several methods to compare the values of
strings. The following table describes some of the value-comparison methods.
Method Name Use

String.Compare Compares the values of two strings. Returns an integer value.

String.StartsWith Determines if a string begins with the string passed. Returns a
boolean value.
String.IndexOf Returns the index of the first occurrence of a String, or one or
more characters, within this instance.

For more information about value comparison methods and for a complete list
of these methods, see “Comparing Strings” in the .NET Framework SDK
documentation.
For example, the String.Compare method provides a thorough way to compare
the current string object to another string or object. You can use this function to
compare two strings or substrings of two strings.
Additionally, overloads are provided that regard or disregard case and cultural
variance.
Module 7: Strings, Arrays, and Collections 11

The following table shows the three integer values that are returned by the
Compare(string strA, string strB) method.
Value Type Condition

A negative integer strA is less than strB

0 strA equals strB
A positive integer strA is greater than strB

The following code example uses the Compare method to determine whether
two strings are the same.
string MyString = "Hello World!";
Console.WriteLine(String.Compare(MyString, "Hello World!"));

The preceding example displays 0 to the console.

12 Module 7: Strings, Arrays, and Collections

Trim and Pad

Topic Objective
To explain how to use ! Trim Methods Remove Spaces
methods of the
System.String class to trim string
string MyString
MyString == "" Big
Big ";
";
and pad strings. Console.WriteLine("Hello{0}World!",
Console.WriteLine("Hello{0}World!", MyString
MyString );
);
string TrimString = MyString.Trim();
string TrimString = MyString.Trim();
Lead-in Console.WriteLine("Hello{0}World!",
Console.WriteLine("Hello{0}World!", TrimString
TrimString ););
You can remove or extend //
// outputs the following lines to the console:
outputs the following lines to the console:
the spaces around strings //Hello
//Hello Big
Big World!
World!
by using methods of the //HelloBigWorld!
System.String class. //HelloBigWorld!

! Pad Methods Expand a Specific Number of Characters

string
string MyString
MyString == "Hello
"Hello World!";
World!";
Console.WriteLine(MyString.PadLeft(20,
Console.WriteLine(MyString.PadLeft(20, '-'));'-'));
//
// outputs
outputs the
the following
following line
line to
to the
the console:
console:
//--------Hello
//--------Hello World!
World! to
to the
the console.
console.

*ILLEGAL FOR NON-TRAINER USE**

When you want to remove or extend the spaces around strings, the
System.String class provides methods for trimming and padding strings.

Trimming
When you are parsing a sentence into individual words, you might have white
spaces on either end of a word. You can use one of the trim methods in the
System.String class to remove any number of spaces from the beginning or end
of the string.
The following table describes two of the available trim methods.
Method Name Use

String.Trim Removes white spaces from the beginning and end of a string.
String.Remove Removes a specified number of characters from a specified index
position in a string.

For example, you can easily remove white spaces from both ends of a string by
using the String.Trim method, as shown in the following code example.
string MyString = " Big ";
Console.WriteLine("Hello{0}World!", MyString );
string TrimString = MyString.Trim();
Console.WriteLine("Hello{0}World!", TrimString );

This code outputs the following lines to the console:

Hello Big World!
HelloBigWorld!

For a complete list of trim methods in the System.String class, see “Trimming
and Removing Characters” in the .NET Framework SDK documentation.
Module 7: Strings, Arrays, and Collections 13

Padding
System.String also provides methods that you can use to create a new version
of an existing string that is expanded by a specific number of characters.
The following table describes the available pad methods.
Method Name Use

String.PadLeft Right aligns and pads a string, so its rightmost character is a

specified distance from the beginning of the string.
String.PadRight Left aligns and pads a string, so its rightmost character is a
specified distance from the beginning of the string.

For example, the String.PadLeft method creates a new string that moves an
existing string to the right, so its last character is a specified number of spaces
from the first index of the string. White spaces are inserted if you do not use an
override that allows you to specify your own custom padding character.
The following code example uses the PadLeft method to create a new string
with a total length of 20 spaces.
string MyString = "Hello World!";
Console.WriteLine(MyString.PadLeft(20, '-'));

This example displays the following text to the console.

--------Hello World!
14 Module 7: Strings, Arrays, and Collections

Split and Join

Topic Objective
To explain how to use the ! Split Method Is Used to Break Up a String Into an Array of
Split and Join methods to Substrings
break up and concatenate
strings. # String is broken at positions indicated by the specified separator
characters parameter
Lead-in # If the separator parameter is null, the whitespace characters are
The System.String class assumed to be the separator
provides the Split method to
break up strings and the string
string Line
Line == "Hello
"Hello World";
World";
Join method to concatenate string[]
string[] Words == Line.Split(null);
Words Line.Split(null);
strings. //
// Words[0]
Words[0] == "Hello"
"Hello" and
and Words[1]
Words[1] == "World"
"World"

! Join Method Is Used to Concatenate Strings

# A specified separator string is placed between each element of a
string array

*ILLEGAL FOR NON-TRAINER USE**

The System.String class provides the Split method to break up strings and the
Join method to concatenate strings.

The Split Method

You use the Split method to break up a string instance into an array of
For Your Information substrings at the positions that are specified by separator characters. If separator
You should cover the
String.Split method
characters are omitted, that is to say, if the parameter is null, the whitespace
because it is used in the lab. characters are assumed to be the separator. If the separator is a zero-length
string, a single-element array that contains the entire expression string is
returned.
The following example shows how to break up a string into a string array of
words:
string Line = "Hello World";
string[] Words = Line.Split(null);
// Words[0] = "Hello" and Words[1] = "World"

The Join Method

You use the Join method to concatenate a specified separator string between
each element of a specified String array, which yields a single concatenated
string. If the separator is omitted, that is to say null, the space character (" ")
is used. If the separator is a zero-length string (""), all of the items in the list
are concatenated with no delimiters.
Module 7: Strings, Arrays, and Collections 15

StringBuilder
Topic Objective
To explain how to use the ! The String Object is Immutable
StringBuilder method to
modify a string without ! System.Text.StringBuilder – Allows You to Modify a
creating a new object. String Without Creating a New Object
Lead-in StringBuilder
StringBuilder MyStringBuilder
MyStringBuilder == new
new StringBuilder("Hello");
StringBuilder("Hello");
When you want to perform
repeated modifications to a ! You Can Specify the Maximum Number of Characters
string, use the
//
// MyStringBuilder
MyStringBuilder can
can hold
hold aa maximum
maximum of
of 25
25 characters
characters
System.Text.StringBuilder
StringBuilder
StringBuilder MyStringBuilder
MyStringBuilder ==
class to modify a string new
without creating a new new StringBuilder("Hello
StringBuilder("Hello World!",
World!", 25);
25);
object. ! Methods Include:
# Append, AppendFormat, Insert, Remove,
and Replace

*ILLEGAL FOR NON-TRAINER USE**

The String object is immutable. Therefore, every time you use one of the
methods in the System.String class, you create a new string object. When you
want to perform repeated modifications to a string, the overhead that is
associated with creating a new String object can be costly. As an alternative,
you can use the System.Text.StringBuilder class to modify a string without
creating a new object.

Creating a StringBuilder Object

You can create a new instance of the StringBuilder object by initializing your
variable with one of the overloaded constructor methods, as shown in the
following code example:
StringBuilder MyStringBuilder = new StringBuilder("Hello");

Although the StringBuilder object is a dynamic object that allows you to

expand the number of characters in the string that it encapsulates, you can
specify a value for the maximum number of characters that it can hold. This
value is called the capacity of the object and must not be confused with the
length of the string that the current StringBuilder object holds. Any attempt to
expand the StringBuilder class beyond the maximum range causes an
ArgumentOutOfRangeException to be thrown.
The following code example specifies that the MyStringBuilder object can be
expanded to a maximum of 25 spaces.
StringBuilder MyStringBuilder =
new StringBuilder("Hello World!", 25);
16 Module 7: Strings, Arrays, and Collections

StringBuilder Methods
The following table describes the methods that you can use to modify the
contents of the StringBuilder object.
Method Name Use

StringBuilder.Append Appends information to the end of the current

StringBuilder object.
StringBuilder.AppendFormat Replaces zero or more format specifications with
the appropriately formatted value of an object.
StringBuilder.Insert Inserts a string or object into the specified index of
the current StringBuilder object.
StringBuilder.Remove Removes a specified number of indexes from the
current StringBuilder object.
StringBuilder.Replace Replaces a specified index or character with the
passed character.
Module 7: Strings, Arrays, and Collections 17

C# Specifics
Topic Objective ! C# string Type Is a String of Unicode Characters
To explain what the string # Alias for System.String
type is in the .NET
Framework and to describe # Equality operators (== and !=) compare the values of string objects,
the functions of the +, [ ], not references
and != operators, and @- # The + operator concatenates strings
quoting.
string
string aa == "\u0068ello
"\u0068ello ";
";
Lead-in string
string bb == "world";
"world";
The string type represents Console.WriteLine(
Console.WriteLine( aa ++ bb ==
== "hello
"hello world"
world" );//True
);//True
a string of Unicode
characters; string is an # The [ ] operator accesses individual characters of a string
alias for System.String in
char
char xx == "test"[2];
"test"[2]; //
// xx == 's';
's';
the .NET Framework.

# With @-quoting, escape sequences are not processed

@"c:\Docs\Source\a.txt"
@"c:\Docs\Source\a.txt"
//
// rather
rather than
than "c:\\Docs\\Source\\a.txt"
"c:\\Docs\\Source\\a.txt"
*****************************ILLEGAL FOR NON-TRAINER USE******************************
The string type represents a string of Unicode characters; string is an alias for
System.String in the .NET Framework.
Although string is a reference type, the equality (==) operator and the
inequality (!=) operator are defined to compare the values of string objects, not
the references. Comparing the values of string objects makes testing for string
equality more intuitive, as in the following example:
string a = "hello";
string b = "hello";
Console.WriteLine( a == b ); // output: True -- same value

The + operator concatenates strings, as in the following example:

string a = "good " + "morning";

The [ ] operator accesses individual characters of a string, as in the following

example:
char x = "test"[2]; // x = 's';

String literals are of type string and can be written in two forms: quoted and
@-quoted. Quoted string literals are enclosed in quotation marks ("), as in the
following example:
"good morning" // a string literal

Quoted string literals can also contain any character literal, including escape
sequences, as in the following example:
string a = "\\\u0066\n"; // backslash, letter f, new line
18 Module 7: Strings, Arrays, and Collections

@-quoted string literals start with @ and are enclosed in quotation marks, as in
the following example:
@"good morning" // a string literal

The advantage of using @-quoted string literals is that escape sequences are not
processed. This makes it easy to write a fully qualified file name, as in the
following example:
@"c:\Docs\Source\a.txt"
// rather than "c:\\Docs\\Source\\a.txt"

To include a quoted phrase in an @-quoted string, use two pairs of double

quotation marks, as in the following example:
@"""Ahoy!"" cried the captain." // "Ahoy!" cried the captain.

The following code example uses the C# features that are discussed in this
topic:
using System;
class test
{
public static void Main( String[] args )
{
string a = "\u0068ello ";
string b = "world";
Console.WriteLine( a + b );
Console.WriteLine( a + b == "hello world" );
}
}

The preceding code example displays the following output to the console:
hello world
True
Module 7: Strings, Arrays, and Collections 19

Regular Expressions
Topic Objective
To briefly describe how
regular expressions can be
used in the .NET ! Regular Expressions – Powerful Text Processing
Framework.
! Pattern-Matching Notation Allows You to:
Lead-in
Regular expressions allow # Find specific character patterns
you to quickly parse large
amounts of text in order to # Extract, edit, replace, or delete text substrings
find specific character
# Add the extracted strings to a collection to generate
patterns; to extract, edit,
replace, or delete text a report
substrings; and to add the
! Designed to be Compatible With Perl 5
extracted strings to a
collection to generate a
report.

*ILLEGAL FOR NON-TRAINER USE**

This topic provides a brief Regular expressions provide a powerful, flexible, and efficient method to
summary of regular process text. The extensive pattern-matching notation of regular expressions
expressions. Do not spend allows you to quickly parse large amounts of text to find specific character
much time on this slide, but patterns; to extract, edit, replace, or delete text substrings; and to add the
encourage students to refer extracted strings to a collection in order to generate a report.
to the .NET Framework
SDK, especially for details For many applications that deal with strings, such as HTML processing, log file
about using the regular parsing, and HTTP header parsing, regular expressions are an essential tool.
expression classes.
The .NET Framework regular expressions incorporate the most popular features
of other regular expression implementations, such as those used in Perl and
awk. Designed to be compatible with Perl 5 regular expressions, .NET
Framework regular expressions include features that are not yet available in
other implementations, such as right-to-left matching and dynamic compilation.
The .NET Framework regular expression classes are part of the .NET
Framework class library and can be used with any language or tool that targets
the common language runtime, including ASP.NET and Microsoft
Visual Studio® .NET.
A detailed explanation of how to use the regular expression classes is beyond
the scope of this course. For more information about using regular expression
classes, see the .NET Framework SDK documentation.
20 Module 7: Strings, Arrays, and Collections

Terminology – Collections
Topic Objective
To define the term collection
as it is used in this module
and to identify where ! In This Module, the Term Collection Is Used in Its
collections are found in the Broader Sense to Refer to a Group of Items
.NET Framework.
! In the .NET Framework, Collections Are Found in
Lead-in the Namespaces
In this module, the term
collection is used in its # System.Array
broader sense: to describe a
group of items. # System.Collections

*ILLEGAL FOR NON-TRAINER USE**

Do not spend much time on In this module, the term collection is used in its broader sense to refer to a
this slide. The objective of group of items. In the .NET Framework, examples of collections are found in
this slide is to define the the namespaces System.Array, and System.Collections.
term collection clearly,
before discussing the
collections that are found in
the .NET Framework.
Module 7: Strings, Arrays, and Collections 21

" .NET Framework Arrays

Topic Objective
To introduce the topics in
the section.
! System.Array
Lead-in
The System.Array class is ! C# Specifics
the base class of all array
types and contains methods ! Iterating Over
for creating, manipulating,
searching, and sorting ! Comparing
arrays.
! Sorting

*ILLEGAL FOR NON-TRAINER USE**

The System.Array class is the base class of all array types and contains
methods for creating, manipulating, searching, and sorting arrays. The Array
class is not part of the Collections namespace. However, it is still a collection
because it is based on the IList interface.
In an array style of collection, an item in the collection is referred to by the term
element. Specific elements are identified by their array index. The low bound or
lower bound of an Array is the index of its first element.
To understand the functionality of the various collection classes, you must
understand their key interfaces. In this section, you will learn about the
interfaces that are used by the methods of System.Array.
22 Module 7: Strings, Arrays, and Collections

System.Array
Topic Objective
To explain how array types
are used and defined. ! System.Array Is the Base Class of All Array Types
Lead-in ! Arrays Implement the Following Interfaces
The System.Array class is
the base class of all array # ICloneable, IList, ICollection, and IEnumerable
types and contains methods
for creating, manipulating, ! System.Array Has Methods For
searching, and sorting
arrays. # Creating, manipulating, searching, and sorting
! Null, Empty String, and Empty (0 item) Arrays Should Be
Treated the Same
# Therefore, return an Empty array, instead of a
null reference

*ILLEGAL FOR NON-TRAINER USE**

The System.Array class is the base class of all array types and contains
methods for creating, manipulating, searching, and sorting arrays. Arrays are
always allocated on the garbage-collected heap. Arrays can be single
dimensional or multidimensional. You can also create arrays of arrays, called
jagged arrays.
For optimum performance, it is highly recommended that each rank of an array
be zero-based. Additionally, each rank of an array must be zero-based when
passing arrays between programming languages.

Defining an Array Type

You define an array type by specifying the element type of the array, the rank,
or number of dimensions, of the array, and the upper and lower bounds of each
dimension of the array. All of these details are included in any signature of an
array type.
The runtime automatically creates exact array types as they are required. No
separate definition of the array type is needed. Arrays of a particular type can
only hold elements of that type. If you need to manipulate a set of unlike
objects or value types, consider using one of the collection types that are
defined in the System.Collections namespace.
Module 7: Strings, Arrays, and Collections 23

Methods and Properties of System.Array

Some of the methods and properties for the System.Array class are described
in this topic. Many of these methods are used to implement the class’s
interfaces.
System.Array implements the interfaces that are described in the following
table.
Interface Use

ICloneable Supports cloning, which creates a new instance of a class with the
same value as an existing instance.
IList Represents a collection of objects that can be individually
indexed.
ICollection Defines size, enumerators, and synchronization methods for all
collections.
IEnumerable Exposes the enumerator, which supports a simple iteration over a
collection.

The interfaces that are listed in the preceding table are supported not only by
arrays but also by many of the System.Collections classes. Subsequent topics
in this module discuss specific interfaces and the classes that implement them.
The following tables describe some of the public members that are available
through the System.Array class.
Static Method Use

BinarySearch Overloaded. Searches a one-dimensional sorted Array for a

value, using a binary search algorithm.
CreateInstance Overloaded. Initializes a new instance of the Array class.
Sort Overloaded. Sorts the elements in one-dimensional Array
objects.

Property Use

IsFixedSize Gets a value that indicates whether the Array has a fixed size.
IsReadOnly Gets a value that indicates whether the Array is read-only.
Length Gets the total number of elements in all of the dimensions of the
Array.
Rank Gets the rank (number of dimensions) of the Array.

Note The IsFixedSize and IsReadOnly properties are always false unless they
are overridden by a derived class.
24 Module 7: Strings, Arrays, and Collections

The following table describes some of the public instance methods that are
available through the System.Array class.
Instance Method Use

Clone Creates a shallow copy of the Array.

GetEnumerator Returns an IEnumerator for the Array.
GetLength Gets the number of elements in the specified dimension of the
Array.
GetLowerBound Gets the lower bound of the specified dimension in the Array.
GetUpperBound Gets the upper bound of the specified dimension in the Array.
GetValue Overloaded. Gets the values of the Array elements at the
specified indexes.
SetValue Overloaded. Sets the specified Array elements to the specified
value.

For complete lists of public members of the System.Array class, see “Array
Members” in the .NET Framework SDK documentation.

Empty Arrays
Nulls should only be returned by reference properties that refer to another
object or component. String and Array properties should never return null,
because a programmer typically does not expect null in this context. For
example, a programmer typically would assume that the following code works:
public void DoSomething(…) {
string[] sa = SomeOtherFunc();
// The following line assumes sa is never null
if (sa.Length > 0) {
// do something else
}
}

Generally, null, empty string, and empty (0 item) arrays should be treated in the
same way. Therefore, return an Empty array, instead of a null reference.
Module 7: Strings, Arrays, and Collections 25

C# Specifics
Topic Objective ! C# Array Indexes Start at Zero
To explain features that are
unique to C# arrays. ! Declaring an Array – Size Is Not Part of Its Type
Lead-in int[]
int[] numbers;
numbers; //
// declare
declare numbers
numbers as
as
C# arrays are similar to //
// an int array of
an int array of any
any size
size
arrays in most other popular ! Creating an Array
languages, but you should
be aware of the differences int[]
int[] numbers
numbers == new
new int[5];
int[5]; //
// declare
declare and
and create
create
that are presented in this
topic. ! Initializing an Array
int[]
int[] numbers
numbers == new
new int[5]
int[5] {1,
{1, 2,
2, 3,
3, 4,
4, 5};
5};
! Using System.Array Members
int[]
int[] numbers
numbers == {1,
{1, 2,
2, 3,
3, 4,
4, 5};
5};
int LengthOfNumbers
int LengthOfNumbers == numbers.Length;
numbers.Length;

*ILLEGAL FOR NON-TRAINER USE**

C# arrays are zero-indexed. That means the array indexes start at zero. Arrays
in C# and arrays in most other popular languages work similarly, but there are a
few differences that you should be aware of.
When declaring an array, the brackets ([]) must come after the type, and not
after the identifier. Placing the brackets after the identifier is not legal syntax in
C#, as shown in the following example:
int[] table; // not int table[];

In addition, and unlike the C language, the size of the array is not part of its
type. This allows you to declare and assign to an array any array of int objects,
regardless of the array’s length, as in the following examples.
int[] numbers; // declare numbers as an int array of any size

numbers = new int[10]; // numbers is a 10-element array

numbers = new int[20]; // now it's a 20-element array

26 Module 7: Strings, Arrays, and Collections

Declaring an Array
C# supports single-dimensional arrays and multidimensional arrays, which are
also know as rectangular arrays, and jagged arrays.
The following code examples show how to declare each of these arrays:
int[] numbers; // single-dimensional array

string[,] names; // multidimensional array

byte[][] scores; //Array-of-arrays

Instantiating an Array
Declaring arrays, as shown in the preceding examples, does not actually create
the arrays. As discussed later in this topic, arrays in C# are objects and must be
instantiated.
The following code examples show the syntax to create an array for each of the
arrays already discussed:
int[] numbers = new int[5]; // Single-dimensional array

string[,] names = new string[5,4]; // Multi-dimensional array

byte[][] scores = new byte[5][]; // Array-of-arrays

for (int x = 0; x < scores.Length; x++)
{
scores[x] = new byte[4];
}
Module 7: Strings, Arrays, and Collections 27

The following example shows a complete C# program that declares and

instantiates arrays as discussed in this topic.
using System;
class DeclareArraysSample
{
public static void Main()
{
// Single-dimensional array
int[] numbers = new int[5];

// Multidimensional array
string[,] names = new string[5,4];

// Array-of-arrays (jagged array)

byte[][] scores = new byte[5][];

// Create the jagged array

for (int i = 0; i < scores.Length; i++)
{
scores[i] = new byte[i+3];
}

// Print length of each row

for (int i = 0; i < scores.Length; i++)
{
Console.WriteLine("Length of row {0} is {1}",
i, scores[i].Length);
}
}
}

The preceding program displays the following output:

Length of row 0 is 3
Length of row 1 is 4
Length of row 2 is 5
Length of row 3 is 6
Length of row 4 is 7

Initializing Arrays
C# provides simple and straightforward ways to initialize arrays when they are
declared, by enclosing the initial values in curly braces ( {} ).

Important If an array is not initialized when it is declared, array members are

automatically initialized to the default initial value for the array type.
28 Module 7: Strings, Arrays, and Collections

Single-Dimensional Array
The following examples show different ways to initialize single-dimensional
arrays:
int[] numbers = new int[5] {1, 2, 3, 4, 5};

string[] names = new string[3] {"Matt", "Joanne", "Robert"};

You can omit the size of the array, as in the following examples:
int[] numbers = new int[] {1, 2, 3, 4, 5};

string[] names = new string[] {"Matt", "Joanne", "Robert"};

If an initializer is provided, you can also omit the new statement, as in the
following examples:
int[] numbers = {1, 2, 3, 4, 5};

string[] names = {"Matt", "Joanne", "Robert"};

Multidimensional Array
The following examples show different ways to initialize multidimensional
arrays:
int[,] numbers = new int[3, 2] { {1, 2}, {3, 4}, {5, 6} };

string[,] siblings = new string[2, 2] { {"Mike","Amy"},

{"Mary","Albert"} };

You can omit the size of the array, as in the following examples:
int[,] numbers = new int[,] { {1, 2}, {3, 4}, {5, 6} };

string[,] siblings = new string[,] { {"Mike","Amy"},

{"Mary","Ray"} };

If an initializer is provided, you can also omit the new statement, as in the
following examples:
int[,] numbers = { {1, 2}, {3, 4}, {5, 6} };

string[,] siblings = { {"Mike", "Amy"}, {"Mary", "Albert"} };

Module 7: Strings, Arrays, and Collections 29

Jagged Array (Array-of-Arrays)

The following examples show different ways to initialize jagged arrays. You
can initialize jagged arrays by using the following style:
int[][] numbers = new int[2][] { new int[] {2,3,4},
new int[] {5,6,7,8,9} };

You can omit the size of the first array, as in the following example:
int[][] numbers = new int[][] { new int[] {2,3,4},
new int[] {5,6,7,8,9} };

Accessing Array Members

Accessing array members in C# is straightforward and similar to how you
access array members in C and C++. For example, the following code creates
an array called numbers and then assigns 5 to the fifth element of the array:
int[] numbers = {10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0};
numbers[4] = 5;

The following code example declares a multidimensional array and assigns 5 to

the member located at [1, 1]:
int[,] numbers = { {1, 2}, {3, 4}, {5, 6}, {7, 8}, {9, 10} };
numbers[1, 1] = 5;

The following code example shows how to access a member of a jagged array:
int[][] numbers = new int[][]
{
new int[] {1, 2},
new int[] {3, 4}
};
numbers[1][1] = 5;

Arrays Are Objects

Arrays in C# are actually objects. System.Array is the abstract base type of all
array types. Therefore, you can use the properties and other class members of
System.Array.
For example, you can use the Length property to get the length of an array. The
following code example assigns the length of the numbers array, which is 5, to
a variable called LengthOfNumbers:
int[] numbers = {1, 2, 3, 4, 5};
int LengthOfNumbers = numbers.Length;

The System.Array class provides many other useful methods and properties,
such as methods for sorting, searching, and copying arrays.
30 Module 7: Strings, Arrays, and Collections

Iterating Over
Topic Objective ! System.Array and System.Collections Classes
To explain the role of the
IEnumerable and
Implement IEnumerable Interface and its
IEnumerator interfaces in GetEnumerator Method
collections.
! Enumerator Classes Implement IEnumerator
Lead-in
A .NET Framework interface # Members: MoveNext, Reset, and Current
provides a way to group a
int[]
int[] numbers
numbers == new
new int[5]
int[5] {1,
{1, 2,
2, 3,
3, 4,
4, 5};
5};
set of related members that
IEnumerator e = numbers.GetEnumerator();
IEnumerator e = numbers.GetEnumerator();
can be used to perform a
while
while (e.MoveNext())
(e.MoveNext()) {{
particular action.
Console.WriteLine("Number:
Console.WriteLine("Number: {0}", {0}", (int)e.Current);
(int)e.Current);
}}
//
// alternatively
alternatively
foreach
foreach (int
(int ii in
in numbers)
numbers)
{{
Console.WriteLine("Number:
Console.WriteLine("Number: {0}",{0}", i);
i);
}}
*****************************ILLEGAL FOR NON-TRAINER USE******************************

Emphasize the difference To understand the functionality of the various collection classes, you must
between enumeration and understand the key interfaces of the collection classes. A .NET Framework
an enumerator. interface provides a way to group a set of related members that can be used to
perform a particular action.
For example, a client of an object of any class that implements the
IEnumerable interface can obtain an enumerator object for that class. The
System.Array class and all of the System.Collections classes support the
IEnumerable interface.

Note It is easy to confuse the term enumerator with enumeration. However,

enumerator and enumeration are very different concepts. Enumeration, an
enum type in C#, is a distinct type with named constants, as in the following
example:
enum Color {Red,Green,Blue}

Support for IEnumerable and the GetEnumerator Method

These classes inherit from IEnumerable and implement its single method
GetEnumerator. The GetEnumerator method returns an enumerator that
implements the IEnumerator interface.
Enumerators are intended to be used only to read data in the collection. You
cannot use enumerators to modify the underlying collection. The enumerator is
required to be safe. In other words, enumerators must have a fixed view of the
items in a collection that remain the same, even if the collection is modified.
For example, if you call GetEnumerator on a collection at the point in time
when the collection contains the elements 1, 2, and 3, the enumerator object that
is returned by this method must always produce 1, 2, and 3 when it is iterated
over, even if the collection is later changed.
Module 7: Strings, Arrays, and Collections 31

Using Enumerators with Collections

When working with collections, you typically implement an enumerator in one
of the following ways:
! The enumerator makes a copy of all of the items in the collection.
Making a copy of a large collection guarantees safety but imposes a severe
penalty in performance and memory utilization for large collections and
therefore is usually not done.
! The enumerator has a reference to the collection.
If the enumerator implementation uses a reference to the collection, the
copy penalty is avoided. However, safety must be guaranteed by another
means.
If the collection is static or unchanging, you need take no additional action
to ensure safety. The .NET Framework collections are typically not static.
Instead, they implement a versioning mechanism. Every time a .NET
Framework collection changes, the collection’s version number is
incremented. An enumerator that detects that the collection’s version
number has changed after the enumerator was created throws an
InvalidOperationException that should be caught and handled by the
enumerator’s client.

The IEnumerator interface has the Current public instance property. The
Current property gets the current element in the collection.
An enumerator maintains a reference to the item in the collection that is
currently being enumerated. The enumerator is in an invalid state if it is
positioned before the first element in the collection or after the last element in
the collection. When the enumerator is in an invalid state, calling Current
throws an exception.
The IEnumerator interface also requires the following public instance
methods.
Method Use

MoveNext Advances the enumerator to the next element of the collection.

Reset Sets the enumerator to its initial position, which is before the first
element in the collection.

Initially, the enumerator is positioned before the first element in the collection.
Reset also brings the enumerator back to this position. Therefore, after an
enumerator is created or after a Reset, you must call MoveNext to advance the
enumerator to the first element of the collection before reading the value of
Current.
Current returns the same object until MoveNext or Reset is called.
After the end of the collection is passed, the enumerator returns to an invalid
state. At this time, calling MoveNext returns false. Calling Current throws an
exception if the last call to MoveNext returned false.
32 Module 7: Strings, Arrays, and Collections

The following code example shows how to iterate over a collection. In this
example, the collection is an instance of System.Array.
int[] numbers = new int[5] {1, 2, 3, 4, 5};
IEnumerator e = numbers.GetEnumerator();
while (e.MoveNext()) {
Console.WriteLine("Number: {0}", (int)e.Current);
}

This code outputs:

Number: 1
Number: 2
Number: 3
Number: 4
Number: 5

Using foreach to Iterate Through an Array

C# provides the foreach statement, which is a less verbose way to iterate
through the elements of an array. For example, the following code example
creates an array called numbers and iterates through it with the foreach
statement:
int[] numbers = {4, 5, 6, 1, 2, 3, -2, -1, 0};
foreach (int i in numbers) {
System.Console.WriteLine("Number: {0}", i);
}
Module 7: Strings, Arrays, and Collections 33

Comparing
Topic Objective ! To Sort and Search, Collections Must Be Able to Compare Items
To explain how the ! IComparer’s Compare Method Compares Two Objects of Any Type
IComparer and int
IComparable interfaces are int Compare(
Compare( object
object x,
x, object
object yy );
);
used to sort and order a # Comparer class is the default implementation of IComparer
collection’s items. Its Compare method uses IComparable.CompareTo
Lead-in ! IComparable’s CompareTo Method Compares the Current Instance
To sort a collection, you to an Object of the Same Type
must be able to compare int
and order the items of the int CompareTo(
CompareTo( object
object anObject
anObject );
);
collection. ! CompareTo Returns

Value Meaning
Less than zero Instance is less than object
Zero Instance is equal to object
Greater than zero Instance is greater than object
*****************************ILLEGAL FOR NON-TRAINER USE******************************
To sort a collection, you must be able to compare and order the items of the
collection. The IComparer and IComparable interfaces are used to sort and
order a collection’s items.
The IComparer interface’s Compare method compares two objects of any
type and returns a value that indicates whether one object is less than, equal to,
or greater than the other.
The Compare method provides the sort order of a collection and is also used in
conjunction with the Array.BinarySearch method.

Default Implementation of IComparer

The Comparer class provides the default implementation of the IComparer
interface.
The Comparer class’s Compare(object a, object b) method is implemented as
follows:
! If a implements IComparable, then a.CompareTo(b) is returned.
! Otherwise, if b implements IComparable, then b.CompareTo(a) is
returned.

The IComparable interface has a single CompareTo method that compares

the current instance with another object of the same type.
34 Module 7: Strings, Arrays, and Collections

Return Values of CompareTo

The value returned by the CompareTo method is a 32-bit signed integer that
indicates the relative order of the instance and the object that is passed as a
parameter, as in the following example:
int CompareTo(object anObject);

The following table describes the possible meanings of the return value.
Value Meaning

Less than zero This instance is less than anObject.

Zero This instance is equal to anObject.
Greater than zero This instance is greater than anObject.

By definition, any object compares greater than a null reference, and two null
references compare equal to each other.

Issues with Using IComparable.CompareTo

The parameter, anObject, must be the same type as the class or value type that
implements this interface. Otherwise, ArgumentException is thrown.
The default comparison procedures use the Thread.CurrentCulture of the
current thread unless it is otherwise specified. String comparisons may have
different results depending on the culture.
To perform case-insensitive comparisons on strings, you can use the
CaseInsensitiveComparer class’s implementation of the IComparer
interface.
Module 7: Strings, Arrays, and Collections 35

Sorting
Topic Objective
To explain how to compare ! Sort Method Using Element’s IComparable.CompareTo
and order the items of a
collection by using the Array.Sort(
Array.Sort( anArray
anArray );
);
IComparer and
IComparable interfaces. ! IComparable.CompareTo Design Pattern
Knowledge of this topic is
required for the lab. public
public int
int CompareTo(Object
CompareTo(Object anObject)
anObject) {{
if
if (( anObject
anObject ==== null)
null) return
return 1;
1;
Lead-in if
Some collections, such as if (( !(anObject
!(anObject isis <classname>)
<classname>) )) {{
throw
throw new
new ArgumentException();
ArgumentException(); }}
Array, sort their items when //
their Sort method is called. // Do comparison and
Do comparison and return
return aa
//
// negative integer if instance
negative integer if instance << anObject
anObject
// 0 if instance == anObject
// 0 if instance == anObject
//
// positive
positive integer
integer if
if instance
instance >> anObject
anObject
}}

*ILLEGAL FOR NON-TRAINER USE**

Some collections, such as Array, sort their items when their Sort method is
called. Overloaded versions of the Sort method allow you to supply an
IComparer implementation in the method call that is used to perform the
ordering of the elements. These overloaded versions of the Sort method provide
you with the flexibility to resort the same collection of items by using different
IComparer implementations.
If you use the array’s public static void Sort(Array) method, the default
Comparer class implementation of IComparer is used, and the array’s
elements are sorted by using the elements’ implementation of the CompareTo
method of the IComparable interface.
Other collection classes, such as SortedList, have constructors whose
parameters determine the sort order. These classes are less flexible than classes
that implement a sort method because after they are constructed their sort
ordering cannot be changed.
36 Module 7: Strings, Arrays, and Collections

Demonstration: Sorting and Enumerating an Array

Topic Objective
To demonstrate how to sort
and enumerate an array.
Lead-in
In this demonstration, we
will sort an array by using
the CompareTo method
when the value type or class
of the items in the collection
implements the
IComparable interface.

*ILLEGAL FOR NON-TRAINER USE**

As stated in Sorting in this module, you can sort an array by using the
CompareTo method when the value type or class of the items in the collection
implements the IComparable interface.
In this demonstration, an Employee class contains an employee’s name, level
For Your Information number, and hiring date. To sort an array of Employees based on increasing
You should carefully cover
the CompareTo method
level numbers where equal level numbers are then ordered by increasing hiring
because it is used in the lab. date, implement the following:
using System;

namespace ArraySorting
{
public class Employee : IComparable
{
public string name;
public int level;
public DateTime hiringDate;

public Employee(
string name,int level,DateTime hiringDate) {
this.name = name;
this.level=level;
this.hiringDate=hiringDate;
}

public int CompareTo(Object anObject) {

if (anObject == null) return 1;
if ( !(anObject is Employee) ) {
throw new ArgumentException();
}

(Code continued on the following page.)

Module 7: Strings, Arrays, and Collections 37

Employee anEmployee = (Employee)anObject;

if ( level < anEmployee.level ) return -1;
else {
if ( level == anEmployee.level ) {
if (hiringDate <
anEmployee.hiringDate)
return -1;
else {
if ( hiringDate ==
anEmployee.hiringDate)
return 0;
else return 1;
}
}
else return 1;
}
}
}

public class ArraySort {

public static void Main() {

// Create and initialize a new Array instance.

Employee[] myEmployees = new Employee[10];
myEmployees[0] = new Employee(
"a",2,new DateTime(1990,1,1));
myEmployees[1] = new Employee(
"b",2,new DateTime(2000,1,1));
myEmployees[2] = new Employee(
"c",2,new DateTime(1990,1,1));
myEmployees[3] = new Employee(
"d",4,new DateTime(2000,1,1));
myEmployees[4] = new Employee(
"e",4,new DateTime(1990,1,1));
myEmployees[5] = new Employee(
"f",4,new DateTime(2000,1,1));
myEmployees[6] = new Employee(
"g",1,new DateTime(1990,2,5));
myEmployees[7] = new Employee(
"h",1,new DateTime(2000,1,1));
myEmployees[8] = new Employee(
"i",1,new DateTime(1990,1,1));
myEmployees[9] = new Employee(
"j",0,new DateTime(2001,1,1));

// Display the values of the Array.

Console.WriteLine(
"The Array instance initially contains values:"
);
PrintIndexAndValues( myEmployees );

// Sort the values of the Array.

Array.Sort( myEmployees );

(Code continued the following page.)

38 Module 7: Strings, Arrays, and Collections

// Display the values of the Array.

Console.WriteLine( "After sorting:" );
PrintIndexAndValues( myEmployees );
}

public static void PrintIndexAndValues(

Array myEmployees ) {

foreach ( Employee e in myEmployees ) {

Console.WriteLine(
"name: {0} \tlevel: {1} \tdate:{2:d}",
e.name, e.level, e.hiringDate);
}

}
}
}

The preceding code displays the following output to the console:

The Array instance initially contains values:
name: a level: 2 date:1/1/1990
name: b level: 2 date:1/1/2000
name: c level: 2 date:1/1/1990
name: d level: 4 date:1/1/2000
name: e level: 4 date:1/1/1990
name: f level: 4 date:1/1/2000
name: g level: 1 date:2/5/1990
name: h level: 1 date:1/1/2000
name: i level: 1 date:1/1/1990
name: j level: 0 date:1/1/2001
After sorting:
name: j level: 0 date:1/1/2001
name: i level: 1 date:1/1/1990
name: g level: 1 date:2/5/1990
name: h level: 1 date:1/1/2000
name: c level: 2 date:1/1/1990
name: a level: 2 date:1/1/1990
name: b level: 2 date:1/1/2000
name: e level: 4 date:1/1/1990
name: d level: 4 date:1/1/2000
name: f level: 4 date:1/1/2000
Module 7: Strings, Arrays, and Collections 39

" .NET Framework Collections

Topic Objective
To introduce the topics in
the section.
! Examples of System.Collections Classes
Lead-in
The System.Collections ! Lists
namespace contains
interfaces and classes that ! Dictionaries
define various collections of
objects, such as lists, ! SortedList
queues, arrays, hashtables,
! Collection Usage Guidelines
and dictionaries.
! Type Safety and Performance

*ILLEGAL FOR NON-TRAINER USE**

The System.Collections namespace contains interfaces and classes that define
various collections of objects, such as lists, queues, arrays, hashtables, and
dictionaries.
40 Module 7: Strings, Arrays, and Collections

Examples of System.Collections Classes

Topic Objective ! ArrayList
To show some of the
collection classes in the # Implements IList by using a dynamically-sized array
System.Collections ! DictionaryBase
namespace.
# Provides abstract base class for strongly-typed collection of
Lead-in associated keys and values
Let’s look briefly at some of
the collection classes in the ! Hashtable
System.Collections # Represents a collection of keys and values that are organized
namespace. around the key’s hash code
! SortedList
# Represents the collection of keys and values, sorted by keys and
accessible by key and index
! BitArray, Queue, Stack, CollectionBase, ReadOnlyCollectionBase

*ILLEGAL FOR NON-TRAINER USE**

Do not spend a lot of time The following table shows some of the collection classes in the
on this slide. Just introduce System.Collections namespace.
students to some commonly
used collection classes and Class Description
encourage them to refer to
the .NET Framework SDK ArrayList Implements the IList interface by using an array whose
for more information. size is dynamically increased as required.
BitArray Manages a compact array of bit values, which are
represented as Booleans, where true indicates that the bit
is on (1) and false indicates the bit is off (0).
CollectionBase Provides the abstract base class (MustInherit in
Microsoft Visual Basic®) for a strongly-typed collection.
DictionaryBase Provides the abstract base class (MustInherit in
Visual Basic) for a strongly-typed collection of
associated keys and values.
Hashtable Represents a collection of associated keys and values that
are organized around the hash code of the key.
Queue Represents a first-in, first-out collection of objects.
ReadOnlyCollectionBase Provides the abstract base class (MustInherit in
Visual Basic) for a strongly-typed read-only collection.
SortedList Represents a collection of associated keys and values that
are sorted by the keys and are accessible by key and by
index.
Stack Represents a simple last-in-first-out collection of type
Object.
Module 7: Strings, Arrays, and Collections 41

Lists
Topic Objective
To describe the public
instance members that the
IList interface implements. ! IList – Interface for Classes That Represent an Ordered
Collection of Objects That Can Be Individually Indexed
Lead-in
IList is an interface for ! Some Classes That Implement IList
classes that represent an
ordered collection of objects # Array, ArrayList, StringCollection, and
that can be individually TreeNodeCollection
indexed. Array, ArrayList,
StringCollection, and ! Methods Include:
TreeNodeCollection are
some of the classes that # Add, Clear, Contains, Insert, IndexOf, Remove, and
implement IList. RemoveAt

*ILLEGAL FOR NON-TRAINER USE**

IList is an interface for classes that represent an ordered collection of objects
that can be individually indexed. Array, ArrayList, StringCollection, and
TreeNodeCollection are some of the classes that implement IList.
The following tables describe the public instance properties that the IList
interface implements.
Property Use

IsFixedSize When implemented by a class, gets a value indicating whether the IList
has a fixed size.
IsReadOnly When implemented by a class, gets a value indicating whether the IList
is read-only.
Item When implemented by a class, gets or sets the element at the specified
index.
In C#, this property is the indexer for the IList class.
42 Module 7: Strings, Arrays, and Collections

The following table describes the public instance methods that the IList
interface defines.
Method Use

Add When implemented by a class, adds an item to the IList.

Clear When implemented by a class, removes all items from the IList.
Contains When implemented by a class, determines whether the IList contains a
specific value.
IndexOf When implemented by a class, determines the index of a specific item in
the IList.
Insert When implemented by a class, inserts an item to the IList at the
specified position.
Remove When implemented by a class, removes the first occurrence of a specific
object from the IList.
RemoveAt When implemented by a class, removes the IList item at the specified
index.
Module 7: Strings, Arrays, and Collections 43

Demonstration: ArrayList
Topic Objective
To demonstrate how
ArrayList implements the
IList interface by using an
array whose size is
dynamically increased as
required.
Lead-in
In this demonstration,
ArrayList implements the
IList interface by using an
array whose size is
dynamically increased as
required.

*ILLEGAL FOR NON-TRAINER USE**

In this demonstration, ArrayList implements the IList interface by using an
array whose size is dynamically increased as required.
using System;
using System.Collections;

class listSample
{

public static void Main(string[] args) {

ArrayList fruit = new ArrayList();
fruit.Add("Apple");
fruit.Add("Pear");
fruit.Add("Orange");
fruit.Add("Banana");
Console.WriteLine ("\nList Contains:");
foreach (string item in fruit) {
Console.WriteLine(item);
}

Console.WriteLine (
"\nResult of Contains method for Kiwi: {0}",
fruit.Contains("Kiwi"));

Console.WriteLine (
"\nAdding Kiwi at Orange:");

fruit.Insert(fruit.IndexOf("Orange"),"Kiwi");
Console.WriteLine ("\nList Contains:");
foreach (string item in fruit) {
Console.WriteLine(item);
}
(Code continued the following page.)
44 Module 7: Strings, Arrays, and Collections

Console.WriteLine (
"\nResult of Contains method for Kiwi: {0}",
fruit.Contains("Kiwi"));

Console.WriteLine (
"\r\nPress Return to exit.");
Console.Read();
}
}

The preceding code example displays the following output to the console:
List Contains:
Apple
Pear
Orange
Banana

Result of Contains method for Kiwi: False

Adding Kiwi at Orange:

List Contains:
Apple
Pear
Kiwi
Orange
Banana

Result of Contains method for Kiwi: True

Press Return to exit.

Module 7: Strings, Arrays, and Collections 45

Dictionaries
Topic Objective
To describe the IDictionary
interface and the classes ! IDictionary is an Interface for Collections of Associated
that it implements. Keys and Values
Lead-in # Each association must have a unique non-null key, but
IDictionary is an interface
for collections of associated
the value of an association can be any object reference,
keys and values. including a null reference
! Collection Classes That Implement IDictionary Include
# Hashtable, DictionaryBase, and SortedList
! Methods Include:
# Add, Clear, Contains, GetEnumerator, and Remove

*ILLEGAL FOR NON-TRAINER USE**

IDictionary is an interface for collections of associated keys and values. Each
association must have a unique non-null key, but the value of an association can
be any object reference, including a null reference.
Hashtable, DictionaryBase, and SortedList are examples of collection classes
that implement IDictionary.
The IDictionary interface allows the contained keys and values in the items in
a collection to be enumerated, but it does not imply any particular sort order.
The IDictionaryEnumerator interface inherits from IEnumerator and adds
members to return the object’s Key and Value fields individually or in a
DictionaryEntry structure.
IDictionary implementations can be divided into the following categories:
! Read-only
You cannot modify a read-only IDictionary.
! Fixed-size
You cannot add or remove elements from a fixed-size IDictionary, but you
can modify existing elements.
! Variable-size
You can add, remove, or modify elements in a variable-size IDictionary.
46 Module 7: Strings, Arrays, and Collections

The following table describes some of the public instance properties that the
IDictionary interface implements.
Property Use

IsFixedSize When implemented by a class, gets a value indicating whether the

IDictionary has a fixed size.
IsReadOnly When implemented by a class, gets a value indicating whether the
IDictionary is read-only.
Item When implemented by a class, gets or sets the element at the
specified index.
In C#, this property is the indexer for the class.
Keys When implemented by a class, gets an ICollection containing the
keys of the IDictionary.
Values When implemented by a class, gets an ICollection containing the
values in the IDictionary.

The following table describes some of the public instance methods that the
IDictionary interface implements.
Method Use

Add When implemented by a class, adds an entry with the provided

key and value to the IDictionary.
Clear When implemented by a class, removes all elements from the
IDictionary.
Contains When implemented by a class, determines whether the
IDictionary contains an entry with the specified key.
GetEnumerator When implemented by a class, returns an
IDictionaryEnumerator for the IDictionary.
Remove When implemented by a class, removes the entry with the
specified key from the IDictionary.

For a complete list of the members of the IDictionary interface, see

“IDictionary Members” in the .NET Framework SDK documentation.
Module 7: Strings, Arrays, and Collections 47

Demonstration: Hashtable
Topic Objective
To demonstrate how to
create a hash table that is
used for searches.
Lead-in
The Hashtable class
represents a collection of
associated keys and values
that are organized on the
basis of the keys’ hash
code.

*ILLEGAL FOR NON-TRAINER USE**

The Hashtable class represents a collection of associated keys and values that
are organized on the basis of the keys’ hash code. The objects that are used as
keys in a Hashtable must implement or inherit the Object.GetHashCode and
Object.Equals methods. If key equality were simply reference equality, the
inherited implementation of these methods would suffice.
Furthermore, these methods must produce the same results when they are called
with the same parameters while the key exists in the Hashtable. Key objects
must be immutable as long as they are used as keys in the Hashtable.
The foreach statement of the C# language requires the type of the elements in
the collection. Because each element of the Hashtable is a key-and-value pair,
the element type is not the type of the key or the type of the value. Instead, the
element type is DictionaryEntry, as in the following example:
foreach (DictionaryEntry myEntry in myHashtable) {...}
48 Module 7: Strings, Arrays, and Collections

The code in this demonstration creates a hash table of employee numbers and
names, and searches the table for an employee by number and by name.
using System;
using System.Collections;

class HashTableSample
{
public static void Main(String[] args)
{
//create hash table of employee numbers and names
Hashtable table = new Hashtable();
table.Add("0123","Jay");
table.Add("0569","Brad");
table.Add("1254","Brian");
table.Add("6839","Seth");
table.Add("3948","Rajesh");
table.Add("1930","Lakshan");
table.Add("9341","Kristian");
printTable(table);

//now we'll look to see if an employee is in the table

//by key
Console.Write(
"Search for employee by key, enter ID ==-> ");
string input = Console.ReadLine();
if (table.Contains(input)) {
Console.WriteLine("Found {0} in the list.",input);
}
else {
Console.WriteLine("Employee {0} not found.",input);
}
//by value
Console.Write(
"Search for employee by value, enter name ==-> ");
input = Console.ReadLine();
if (table.ContainsValue(input)) {
Console.WriteLine("Found {0} in the list.",input);
}
else {
Console.WriteLine("Employee {0} not found.",input);
}
printTable(table);
// remove an employee by key
Console.Write("Remove employee by key, enter ID ==-> ");
input = Console.ReadLine();
table.Remove(input);
printTable(table);
Console.WriteLine ("\r\nPress Return to exit.");
Console.Read();
}

(Code continued on the following page.)

Module 7: Strings, Arrays, and Collections 49

public static void printTable(Hashtable table) {

Console.WriteLine ("Current list of employees:\n");
Console.WriteLine ("ID\tName");
Console.WriteLine ("--\t----");
foreach (DictionaryEntry d in table) {
Console.WriteLine ("{0}\t{1}", d.Key, d.Value);
}
}
}

The preceding code example displays the following output or similar output to
the console:
Current list of employees:

ID Name
-- ----
1254 Brian
6839 Seth
3948 Rajesh
1930 Lakshan
0123 Jay
0569 Brad
9341 Kristian
Search for employee by key, enter ID ==-> 111
Employee 111 not found.
Search for employee by value, enter name ==-> Jay
Found Jay in the list.
Current list of employees:

ID Name
-- ----
1254 Brian
6839 Seth
3948 Rajesh
1930 Lakshan
0123 Jay
0569 Brad
9341 Kristian
Remove employee by key, enter ID ==-> 9341
Current list of employees:

ID Name
-- ----
1254 Brian
6839 Seth
3948 Rajesh
1930 Lakshan
0123 Jay
0569 Brad

Press Return to exit.

50 Module 7: Strings, Arrays, and Collections

SortedList
Topic Objective ! SortedList Maintains Two Arrays for Entries
To explain how arrays are
used in a SortedList and # One array for the keys and another array for the associated values
how to create, initialize, and SortedList
access a SortedList. This SortedList mySL
mySL == new
new SortedList();
SortedList();
//
// Add an entry with aa key
Add an entry with key == "First"
"First" and
and aa value
value == 11
topic is very important
mySL.Add("First",
mySL.Add("First", 1);1);
because its contents are
//
// Increment
Increment the
the value
value of
of the
the entry
entry whose
whose key
key == "First"
"First"
required for the lab.
mySL["First"] = (Int32)mySL["First"]
mySL["First"] = (Int32)mySL["First"] + 1; + 1;
Lead-in
! Count Property – Number of Elements in the SortedList
A SortedList maintains two
arrays internally to store ! Sorted Using a Specific IComparer Implementation or According to
entries to the list: one array the Key's IComparable Implementation
for the keys, and another ! Printing the Keys and Values of a SortedList
array for the associated
values. for
for (( int
int ii == 0;
0; ii << myList.Count;
myList.Count; i++
i++ )) {{
Console.WriteLine( "\t{0}:\t{1}",
Console.WriteLine( "\t{0}:\t{1}",
myList.GetKey(i),
myList.GetKey(i), myList.GetByIndex(i)
myList.GetByIndex(i) );
); }}
*****************************ILLEGAL FOR NON-TRAINER USE******************************
A SortedList maintains two arrays internally to store entries to the list: one
array for the keys, and another array for the associated values. An entry is a
key-and-value pair. A SortedList implements the IDictionary, IEnumerable,
ICollection, and ICloneable interfaces.
The Count property gets the number of elements that are contained in the
SortedList. The Add method is used to add an entry to the SortedList. The [ ]
Operator is used to modify the value of an entry with the specified key.
You can sort the keys of a SortedList according to an IComparer
For Your Information implementation that is specified when the SortedList is instantiated or
You should carefully cover
the SortedList class, the
according to the IComparable implementation that is provided by the keys
Add method, and the [ ] themselves. In either case, a SortedList does not allow duplicate keys.
Operator because they are
Operations on a SortedList tend to be slower than operations on a Hashtable
used in the lab.
because of the sorting. However, the SortedList offers more flexibility by
allowing access to the values through the associated keys or through the
indexes.
A key cannot be a null reference, but a value can be a null reference. Indexes in
the SortedList collection are zero-based.
Module 7: Strings, Arrays, and Collections 51

The following example shows how to create a SortedList, add an entry, modify
an entry’s value, and print out the SortedList’s keys and values.
using System;
using System.Collections;
public class SamplesSortedList {

public static void Main() {

// Create and initialize a new SortedList.

SortedList mySL = new SortedList();
mySL.Add("First", 1);
mySL.Add("Second", 2);
mySL.Add("Third", 3);

// Display the properties and values of the SortedList.

Console.WriteLine( "mySL" );
Console.WriteLine( " Count: {0}", mySL.Count );
Console.WriteLine( " Capacity: {0}", mySL.Capacity );
Console.WriteLine( " Keys and Values:" );
PrintKeysAndValues( mySL );

// increment the value of the entry whose key is "Third"

mySL["Third"] = (Int32)mySL["Third"] + 1;
PrintKeysAndValues( mySL );
}

public static void PrintKeysAndValues( SortedList myList ){

Console.WriteLine( "\t-KEY-\t-VALUE-" );
for ( int i = 0; i < myList.Count; i++ ) {
Console.WriteLine( "\t{0}:\t{1}",
myList.GetKey(i), myList.GetByIndex(i) );
}
Console.WriteLine();
}
}

The preceding code example displays the following output to the console:
mySL
Count: 3
Capacity: 16
Keys and Values:
-KEY- -VALUE-
First: 1
Second: 2
Third: 3

-KEY- -VALUE-
First: 1
Second: 2
Third: 4
52 Module 7: Strings, Arrays, and Collections

Collection Usage Guidelines

Topic Objective
To distinguish between ! Use a Collection instead of an Array:
collections and arrays and
explain when collections are # When Add, Remove, or other methods for manipulating the set
used. of objects are supported. This scopes all related methods to
the collection
Lead-in
Arrays and collections are # When you want to provide a read-only set of objects. System.Array
used similarly, but they objects are always writable
perform differently. - You can add read-only wrappers around internal arrays
! Use Collections to Avoid Inefficiencies
# In the following code, each call to the myObj property creates a
copy of the array. As a result, 2n+1 copies of the array are created:
for
for (int
(int ii == 0;
0; ii << obj.myObj.Count;
obj.myObj.Count; i++)
i++)
DoSomething(obj.myObj[i]);
DoSomething(obj.myObj[i]);

*ILLEGAL FOR NON-TRAINER USE**

Class library designers sometimes need to decide when to use an array and
when to use a collection. Arrays and collections have similar usage models, but
they differ somewhat in performance.

Collections vs. Arrays

When Add, Remove, or other methods for manipulating the collection are
supported, use a collection, instead of an array. Using a collection scopes all
related methods to the collection.
Also, use collections to add read-only wrappers around internal arrays.
System.Array objects are always writable.

Array Valued Properties

Use collections to avoid code inefficiencies. In the following code example,
each call to the myObj property creates a copy of the array. As a result, 2n+1
copies of the array will be created in the following loop:
for (int i = 0; i < obj.myObj.Count; i++)
DoSomething(obj.myObj[i]);
Module 7: Strings, Arrays, and Collections 53

Choosing A Collection Class

Choosing the right Collections class must be done carefully. Using the wrong
collection can unnecessarily restrict how you use it.
Consider the following questions:
! Do you need temporary storage?
• If yes, consider Queue or Stack.
• If no, consider the other collections.
! Do you need to access the elements in a certain order, such as first-in-first-
out, last-in-first-out, or randomly?
• The Queue offers first-in, first-out access.
• The Stack offers last-in, first-out access.
• The rest of the collections offer random access.
! Do you need to access each element by index?
• ArrayList and StringCollection offer access to their elements by the
zero-based index.
• Hashtable, SortedList, ListDictionary, and StringDictionary offer
access to their elements by the key of the element.
• NameObjectCollectionBase and NameValueCollection offer access to
their elements either by the zero-based index or by the key of the
element.
! Will each element contain just one value or a key-singlevalue pair or a key-
multiplevalues combination?
• One value: Use any of the collections based on IList.
• Key-singlevalue pair: Use any of the collections based on IDictionary.
• Key-multiplevalues combination: Consider using or deriving from the
NameValueCollection class in the Collections.Specialized namespace.
! Do you need to sort the elements differently from how they were entered?
• Hashtable sorts the elements by the hash code of the key.
• SortedList sorts the elements by the key, based on an IComparer
implementation.
• ArrayList provides a Sort method that takes an IComparer
implementation as a parameter.
! Do you need fast searches and retrieval of information?
• ListDictionary is faster than Hashtable for small collections of ten
items or less.
! Do you need collections that accept only strings?
• StringCollection (based on IList) and StringDictionary (based on
IDictionary) are in the Collections.Specialized namespace.
54 Module 7: Strings, Arrays, and Collections

Type Safety and Performance

Topic Objective ! System.Collections Items Require a Runtime Object Cast
To discuss runtime casting ! Drawbacks of Runtime Casting
for type safety and the
effects of runtime casting # Type errors found at runtime, rather than at compile time
and boxing and unboxing on # Runtime overhead of casting
performance.
# Runtime overhead of boxing/unboxing operations for value types
Lead-in
The System.Collections ! Type-Specific Collection Classes Can Eliminate Runtime Casting
classes are generic # System.Collections.Specialized namespace contains string-
collections, which ignore specific collections
their items’ true types. # Create your own type-specific collection class by inheriting from a
Generic collections allow System.Collections class and adding type-specific members
classes to be used for items
of any type. ! Ways to Reduce Boxing and Unboxing Operations of Value Types
# Encapsulate value types in a class
# Manipulate value types through interfaces

*ILLEGAL FOR NON-TRAINER USE**

The System.Collections classes are generic collections, which ignore their
items’ true types. Generic collections allow classes to be used for items of any
type.

Drawbacks of Runtime Casting

The System.Collections classes have properties and methods that manipulate
the collection’s items through the item’s System.Object base type. The class’s
members take and return parameters of type System.Object. For example,
IEnumerator.Current returns a System.Object instance.
This use of an object’s base class requires casting a runtime object to obtain the
true type of the object. Casting System.Object instances at run time has two
drawbacks:
! Collection operations with invalid parameter or return types are not flagged
at compile time.
If the cast is invalid, the problem is only detected at run time when an
InvalidCastException is thrown.
! Such casting hurts runtime performance because the .NET runtime must
perform type-checking.

In addition, in the case of a collection of value types, such as an int, casting to

and from System.Object results in boxing and unboxing operations that further
impair performance.
The ideal solution to these two drawbacks would be a language mechanism that
automatically generates a type-specific version of the System.Collections
classes that is similar to the C++ template class mechanism. For example, if you
declared an ArrayList<int>, this object would store int values directly, without
casting and without boxing. This feature is not implemented in the first version
of C#; however, it may be implemented in a later version.
Module 7: Strings, Arrays, and Collections 55

The System.Collections classes provide a simple and powerful way to

implement collections. Carefully evaluate whether the use of these classes in
your programs imposes a significant enough performance penalty to warrant
taking the further action that is described in the following sections.

Strongly-Typed Collections
One way to provide compile-time type-checking and improve the performance
of collection code is to use strongly-typed collections. The
System.Collections.Specialized namespace contains string-specific collection
classes, as described in the following table.
Class Description

NameValueCollection Represents a sorted collection of associated String keys

and String values that can be accessed with the hash
code of the key or with the index.
StringCollection Represents a collection of strings.
StringDictionary Implements a hash table with the key strongly-typed to
be a string, rather than an object.
StringEnumerator Supports a simple iteration over a StringCollections.

Creating Custom Collection Classes

You can also create your own strongly-typed collection by creating your own
custom collection class. Your class can reuse System.Collections functionality
by inheriting from the appropriate System.Collections class. You create the
type-specific class with methods and properties whose parameters and return
types are type-specific.
By using C#’s explicit interface implementation mechanism, which is discussed
in Module 6, “Working with Types,” in Course 2349B, Programming with the
Microsoft .NET Framework (Microsoft Visual C#™ .NET), a class can
implement both non-interface and interface members of the same name.
Explicit interface method implementations are frequently used when you
implement such interfaces as IEnumerable, IEnumerator, ICloneable,
IComparable, ICollection, IList, and IDictionary. By having both sets of
members, clients that expect type-specific or System.Object parameters and
return values can use the custom class.

Techniques for Handling Boxing and Unboxing

Instead of creating a type-specific collection class, you can remove the
overhead of boxing and unboxing by using a reference type, rather than a value
type, for the items in a collection. To accomplish this, you can wrap a value
type in a class, as shown in Module 6, Course 2349B, Programming with the
Microsoft .NET Framework (Microsoft Visual C# .NET).
In some cases, you can reduce boxing and unboxing by using interfaces. Value
types can implement interfaces, but because interfaces are referenced types, you
can only have an interface reference to a boxed value type.
You can define an interface for your value type that has the methods and
properties that are needed to manipulate the value type. The value type instance
must still be boxed when it is inserted into a generic System.Collections object,
but your code will be able to manipulate the item’s value through its interface
without unboxing the item.
56 Module 7: Strings, Arrays, and Collections

For example, in the case of a collection of integer values where you want to be
able to add an integer to an element’s value, you can have your value type
implement an interface, as in the following code:
interface IAdd
{
void Add(int amount);
}

struct IntStruct: IAdd

{
int number;

public IntStruct(int number) {

this.number = number;
}

public int Number {

get { return(number);}
}

public void Add(int amount) {

number += amount;
}

public override string ToString() {

return(number.ToString());
}
}
Module 7: Strings, Arrays, and Collections 57

Lab 7: Working with Strings, Enumerators, and

Collections

*ILLEGAL FOR NON-TRAINER USE**

Objectives
After completing this lab, you will be able to:
! Create an application that parses and formats strings.
! Create an application that uses SortedList collection objects.

Lab Setup
Starter and solution files are associated with this lab. The starter files are in the
folder <install folder>\Labs\Lab07\Starter, and the solution files are in the
folder <install folder>\Labs\Lab07\Solution.

Scenario
In this lab, you are provided with a Visual Studio .NET console application as a
starting point. The application, named WordCount, parses a test string into
words and then determines the number of unique words and the number of
times each word occurs. The results of this analysis are formatted and displayed
on the console.
The application is a modified version of the .NET Framework SDK sample,
Word Count.

Estimated time to complete this lab: 60 minutes

58 Module 7: Strings, Arrays, and Collections

Exercise 1
Sorting Words Alphabetically
In this exercise, you will create a class that breaks up the test string into words
and then stores each word and the number of its occurrences in a SortedList.
By default, the sort order will be based on the alphabetical ordering of the word
keys.

! Modify the WordCount class to sort words alphabetically

1. Open the WordCount project in the starter directory by using Visual Studio
.NET.
2. Open the WordCount.cs file.
3. In the WordCounter class, create a member named wordCounter that is
an instance of the SortedList class.
4. Create a read-only property named UniqueWords that returns the number
of items in wordCounter.
5. Create a public method named GetWordsAlphabeticallyEnumerator that
takes no arguments and returns a wordCounter enumerator object of type
IDictionaryEnumerator.
6. Create a public method named CountStats that takes two out parameters of
type Int64 named numWords and numChars and returns a Boolean.
7. Implement the CountStats method to break up the test string, create the
alphabetically sorted list, and return the word count statistics.
a. Initialize the CountStats method’s out parameters to 0.
b. Use the String.Split method to break up testString into individual
words that are stored in an array of type string named Words.
c. Assign to the out parameter numWords the number of words that are
obtained in step 7.b.
d. For each non-empty string in the array Words:
i. Add the number of characters in the word string to numChars.
ii. If wordCounter does not already contain the string, add a new entry
whose key is the string and whose value is 1. The value represents
the number of occurrences of the word. Otherwise, increment by one
the value of the existing entry.

Tip For information about and examples of the IDictionary methods

named Add and Contains, see Dictionaries and Demonstration: Hashtable
in this module. For an example of how to modify the value of an entry by
using the [] Operator, see SortedList in this module.

iii. Return true.

Module 7: Strings, Arrays, and Collections 59

! Modify the Application class

1. In the Application class's Main method, create an instance of
WordCounter named wc.
2. Create two variables of type Int64 named NumWords and NumChars.
3. Call the wc object’s CountStats method to assign the word and character
counts to NumWord and NumChars respectively.
4. Output to the console the test string WordCounter.testString.
5. Output to the console a two-column header labeled Words and Chars. Use
a tab to separate the columns.
6. Output to the console the number of words, and format this output to occupy
five characters, followed by a tab and the number of characters.

! Test the WordCount application

• Build and run the application. You should see output that is similar to the
following:
For string
Hello world
hello here i am where are you hello you

Words Chars
11 41
60 Module 7: Strings, Arrays, and Collections

Exercise 2
Sorting Words by Number of Occurrences
In this exercise, you will create a nested class that implements the
IComparable interface and whose CompareTo method will result in a
SortedList that is ordered on the basis of the number of occurrences of a word.

! Modify the WordCount class to sort words by occurrences

1. Add a nested class named WordOccurrence that inherits from
IComparable.
2. Add a private member of type int named occurrences.
3. Add a private member of type String named word.
4. Add a constructor that takes two parameters. The first parameter is of type
int, and the second parameter is of type String. The constructor assigns the
first value to occurrences and the second value to word.
5. Add a public method CompareTo that takes an Object parameter and
returns an int.
The code should follow the CompareTo design pattern and return a value
that results in a sort of words that is ordered by the occurrences of each
word in ascending order. Less frequently occurring words should be
followed by more frequently occurring words.
In the case in which the number of occurrences of the instance and the
Object parameter are the same, the sort should be alphabetical by using the
String.Compare method.

Tip For an example of implementing the CompareTo method, see

Demonstration: Sorting and Enumerating an Array in this module.

6. Add two public read-only properties named Occurrences and Word that
return the fields occurrences and word respectively. End the nested class
definition.
7. Back in the WordCounter class itself, add a public method named
GetWordsByOccurrenceEnumerator that returns an object of type
IDictionaryEnumerator. Implement
GetWordsByOccurrenceEnumerator as follows:
a. Create a new SortedList named sl.
b. Iterate through the alphabetically-sorted list named wordCounter by
using an enumerator that is obtained by calling the
GetWordsAlphabeticallyEnumerator method.
i. For each alphabetical list entry, create a new object of type
WordOccurence that is initialized with the alphabetically sorted list
entry’s Value and Key.
ii. Add to sl a new entry whose key field is the new WordOccurence
object and whose value field is set to null.
c. Return an enumerator of sl of type IDictionaryEnumerator.
Module 7: Strings, Arrays, and Collections 61

! Modify the Application class

1. Output the words to be sorted alphabetically by adding code to the
Application class’s Main method to:
a. Obtain an IDictionaryEnumerator object named de by calling the wc
object’s GetWordsAlphabeticallyEnumerator method.
b. Display a message to inform the user that the output that is generated
will display word usage sorted alphabetically. Also inform the user of
the number of unique words.
c. Iterate over the collection and output each entry’s value and key,
formatting them so that the value is displayed in the first column and the
key is displayed in the second column.
2. Output the words sorted by occurrence by adding code to:
a. Assign to de an IDictionaryEnumerator object by calling the wc
object’s GetWordsByOccurrenceEnumerator method.
b. Display a message to inform the user that the output that is generated
will display word usage sorted by occurrence. Also inform the user of
the number of unique words.
c. Iterate over the collection. For each entry, obtain the key field’s
WordCounter.WordOccurrence object and output to the console the
Occurrences property of the WordCounter.WordOccurrence object
in the first column and the object’s Word property in the second
column.
62 Module 7: Strings, Arrays, and Collections

! Test the WordCount application

• Build and run the application. You should see output that is similar to the
following:
For string
Hello world
hello here i am where are you hello you

Words Chars
11 41
Word usage sorted alphabetically (9 unique words)
1: "am"
1: "are"
2: "hello"
1: "Hello"
1: "here"
1: "i"
1: "where"
1: "world"
2: "you"
Word usage sorted by occurrence (9 unique words)
1: am
1: are
1: Hello
1: here
1: i
1: where
1: world
2: hello
2: you
Module 7: Strings, Arrays, and Collections 63

Review
Topic Objective
To reinforce module
objectives by reviewing
key points. ! Strings
Lead-in ! Terminology – Collections
The review questions cover
some of the key concepts ! .NET Framework Arrays
taught in the module.
! .NET Framework Collections

*ILLEGAL FOR NON-TRAINER USE**

1. Enter the code to read an integer from the console and assign it to a variable
named aNumber.
int MyInt = int.Parse(Console.ReadLine());

2. What class should you use to improve performance when you want to
perform repeated modifications to a string?
System.Text.StringBuilder

3. Name and briefly describe the interfaces implemented by System.Array.

ICloneable: Supports cloning, which creates a new instance of a class
with the same value as an existing instance.
IList: Represents a collection of objects that can be individually
indexed.
ICollection: Defines size, enumerators, and synchronization methods
for all collections.
IEnumerable: Exposes the enumerator, which supports a simple
iteration over a collection.

4. What does it mean to say that an enumerator is required to be safe?

The enumerator must have a fixed view of the items in a collection that
remains the same, even if the collection is modified.
64 Module 7: Strings, Arrays, and Collections

5. Create an array that contains the integers 1, 2, and 3. Then use the C#
foreach statement to iterate over the array and output the numbers to the
console.
int[ ] numbers = {1, 2, 3};
foreach (int i in numbers) {
System.Console.WriteLine("Number: {0}", i);
}

6. What is the name of the interface that is implemented by classes that contain
an ordered collection of objects that can be individually indexed? Name the
System.Collections classes that implement this interface.
The IList interface is implemented by Array, ArrayList, StringCollection,
and TreeNodeCollection.

7. What is the name of the interface for collections of associated keys and
values? Name the System.Collections classes that implement this interface.
The IDictionary interface is implemented by Hashtable, DictionaryBase,
and SortedList.

8. Generic collection classes require runtime type-casting of their items to

obtain the true type of the items in the collection classes. Name the issues
raised by runtime casting.
Type-checking cannot be done at compile time.
Performance overhead of casting.
In the case of collection of value types, boxing and unboxing operations.
Module 8:
Delegates and Events

Contents
Overview 1
Delegates 2
Multicast Delegates 12
Events 21
When to Use Delegates, Events, and
Interfaces 31
Lab 8: Creating a Simple Chat Server 32
Review 42
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, place or event is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

 2001-2002 Microsoft Corporation. All rights reserved.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Module 8: Delegates and Events iii

Instructor Notes
Presentation: After completing this module, students will be able to:
75 Minutes
! Use the delegate class to create type-safe callback functions and event-
Lab: handling methods.
75 Minutes
! Use the event keyword to simplify and improve the implementation of a
class that raises events.
! Implement events that conform to the Microsoft® .NET Framework
guidelines.

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach
this module.

Required Materials
To teach this module, you need the Microsoft PowerPoint® file 2349B_08.ppt.

Preparation Tasks
To prepare for this module, you should:
! Read all of the materials for this module.
! Practice the demonstrations.
! Complete the lab.
iv Module 8: Delegates and Events

Demonstrations
This section provides demonstration procedures that will not fit in the margin
notes or are not appropriate for the student notes.

Using Delegates
In this demonstration, you will use Microsoft Visual Studio® .NET to run code
in which a delegate to a light object’s method is passed to a switch object.
When the switch object’s state changes, the switch object calls the light
object’s method and passes its new state.
The code for this demonstration is provided in the student notes. The
demonstration files are located in <install folder>\Democode\Mod08\
Demo08.1\Using Delegates.

Multicast Delegates
In this demonstration, you will show students how to add and remove methods
from the invocation list of multicast delegates by using the plus operator (+)
and the minus operator (-).
The code for this demonstration is provided in the student notes. The
demonstration files are located in <install folder>\Democode\Mod08\
Demo08.2\MULTICAST DELEGATES.

Module Strategy
Use the following strategy to present this module:
! Delegates
Use the Delegate Scenario to help students to visualize and comprehend the
concept of delegates. Some students may question the validity of this
scenario. In the real world, a house would never be rewired dynamically, but
you can explain that software programs often need to rebind dynamically.
! Multicast Delegates
Contrast typical multicast delegate use with that of the single delegate
example by using the common scenario of a switch that controls two light
bulbs. Explain how to create and invoke multicast delegates and show how
to use the + and – operators in C# to add and remove methods from the
invocation list of multicast delegates.
! Events
Use the Event Scenario to help students to visualize and comprehend the
concept of events. Emphasize that events are an important building block
for creating classes that can be reused in many different programs, and that
delegates are particularly suited for event handling. Explain how to declare,
connect to, and raise an event.
Introduce the .NET Framework guidelines for delegates and events.
! When to Use Delegates, Events, and Interfaces
Contrast and compare the specific usage characteristics of delegates,
interfaces, and events for providing callback functionality in particular
situations.
Module 8: Delegates and Events 1

Overview
Topic Objective
To provide an overview of
the module topics and
objectives.
! Delegates
Lead-in ! Multicast Delegates
Delegates are the object-
oriented equivalents of ! Events
function pointers.
! When to Use Delegates, Events, and Interfaces

*ILLEGAL FOR NON-TRAINER USE**

In the Microsoft® .NET Framework, delegates are the object-oriented
equivalents of function pointers. However, unlike function pointers, delegates
are type-safe and secure. The common language runtime supports the use of
delegates in callback and event-handling scenarios.
An event is raised by an object or event source in response to an action
performed by a user or some sort of program logic. The event receiver must
then respond to the raised event and perform an action. The event keyword lets
you specify delegates that will be called upon the occurrence of an event.
After completing this module, you will be able to:
! Use the delegate class to create type-safe callback functions and event-
handling methods.
! Use the event keyword to simplify and improve the implementation of a
class that raises events.
! Implement events that conform to the .NET Framework guidelines.
2 Module 8: Delegates and Events

" Delegates
Topic Objective
To provide an overview of
the topics in this section.
! Delegate Scenario
Lead-in
In this section, you will learn ! Declaring a Delegate
about how delegates are
used in the .NET ! Instantiating a Delegate
Framework.
! Calling a Delegate

*ILLEGAL FOR NON-TRAINER USE**

You can use delegates to encapsulate a reference to a method inside a delegate
object. Because delegates are type-safe, secure, managed objects, they offer all
of the advantages of pointers without any of the disadvantages of pointers. For
example, delegates will always point to a valid object and cannot corrupt the
memory of other objects.
Module 8: Delegates and Events 3

Delegate Scenario
Topic Objective 1 - Change in
To illustrate one use of switch position Switch Object
delegates through the invokes switch’s
OnFlip method
scenario of a switch and a
light bulb.
Lead-in Light Object
This scenario of a switch
that controls a light OnFlip method
illustrates one use of
delegates. 2 - OnFlip Method
invokes delegate

OnFlipCallback
Delegate
Delegate object
object method

3 - Delegate invokes light’s 4 - OnFlipCallback method

OnFlipCallback method changes light’s state

*ILLEGAL FOR NON-TRAINER USE**

To run the build slide, click This scenario of a switch that controls a light illustrates one use of delegates.
through the lower-left button The switch object models an electric switch, and the light object models an
on the slide. electric light. The delegate object encapsulates a reference to a light object’s
OnFlipCallback method.
The switch object code could be written without a delegate by referring directly
to the specific light object’s method. However, this approach does not offer the
flexibility to dynamically connect, disconnect, and reconnect various light
object methods to the switch object. You can use a delegate object that
connects the switch object and the light object to achieve this flexibility.
In real life, the preceding scenario would probably not occur as described.
For Your Information While a house would never be rewired dynamically, software programs often
Stress that this scenario
reflects a common scenario
need to dynamically rebind.
to which everyone can When the switch is flipped in the light switch scenario shown in the slide:
relate. While you may not
use the same light switch to 1. The switch object’s OnFlip method is invoked.
turn different lights on and
off at different times, this 2. The OnFlip method invokes the delegate object.
scenario helps you to 3. The delegate object invokes the light object’s OnFlipCallback method.
visualize and comprehend
the concepts behind 4. The OnFlipCallback method changes the state of the light.
delegates.

Delivery Tip
You should briefly preview
the Demonstration: Using
Delegates to provide
students with an overview of
the code that can be used to
implement this scenario.
Defer discussion of delegate
specific code until after the
following topics are covered.
4 Module 8: Delegates and Events

Declaring a Delegate
Topic Objective
To explain how to declare a
delegate.
! A Delegate Declaration Defines a Type That
Lead-in Encapsulates a Method with a Particular Set of
A delegate declaration Arguments and Return Type
defines a type that
encapsulates a method with
a particular set of arguments
and return type. //
// declares
declares aa delegate
delegate for
for aa method
method that
that takes
takes aa single
single
//
// argument
argument of
of type
type string
string and
and has
has aa void
void return
return type
type
delegate
delegate void
void MyDelegate1(string
MyDelegate1(string s);
s);

*ILLEGAL FOR NON-TRAINER USE**

A delegate declaration defines a type that encapsulates a method with a
particular set of arguments and return type. The delegate declaration is
sufficient to define a delegate class whose actual implementation is provided by
the common language runtime.
The following example shows how to declare a delegate for a method that takes
For Your Information a single argument of type string and has a void return type:
The details of how the
common language runtime delegate void MyDelegate1(string s);
creates delegates are
presented later in this
module.
Module 8: Delegates and Events 5

Instantiating a Delegate
Topic Objective
To explain how to instantiate
delegates.
! A Delegate Object Is Created with the new Operator
Lead-in
After you have declared a ! Delegate Objects Are Immutable
delegate type, you can
create a delegate object and //
// instantiating
instantiating aa delegate
delegate to
to aa static
static method
method Hello
Hello
associate it with a particular //
// in
in the
the class
class MyClass
MyClass
method. MyDelegate1
MyDelegate1 aa == new
new MyDelegate1(MyClass.Hello);
MyDelegate1(MyClass.Hello);

//
// instantiating
instantiating aa delegate
delegate to
to an
an instance
instance method
method
// AMethod in object
// AMethod in object p p
MyClass
MyClass pp == new
new MyClass();
MyClass();
MyDelegate1
MyDelegate1 bb == new
new MyDelegate1(p.AMethod);
MyDelegate1(p.AMethod);

*ILLEGAL FOR NON-TRAINER USE**

After you have declared a delegate type, you can create a delegate object and
associate it with a particular method. This topic explains the code used to
instantiate delegates.

Creating a New Delegate Object

Like all objects, a new delegate object is created with the new operator. When
creating a delegate, however, the argument passed to the new operator is
special: it is written like a method call, but without the arguments to the
method. After a delegate is created, the method to which it is associated never
changes: delegate objects are immutable.
When referencing an object, an interesting and useful feature of a delegate is
Delivery Tip that the delegate does not know or care about the class of the object that it
To place the delegate
instantiation code in a fuller
references. It can reference any object as long as the method’s signature
context, refer to the matches the delegate’s signature.
following code example.
A delegate can reference static or instance methods. When referencing instance
methods, the delegate stores not only a reference to the method’s entry point,
but also a reference to the object instance on which the method is invoked.
6 Module 8: Delegates and Events

The following example shows how to declare a delegate named MyDelegate1.

The code illustrates how this delegate can be instantiated to a static or an
instance method. The signature of the method and MyDelegate1 must match;
the method must have a void return and take a single argument of type string.
delegate void MyDelegate1(string s);
...
public class MyClass
{
public static void Hello(string s) {
//...
}
public void AMethod(string s) {
//...
}
}
...

// instantiating a delegate to a static method

MyDelegate1 a = new MyDelegate1(MyClass.Hello);

// instantiating a delegate to object p's AMethod method

MyClass p = new MyClass();
MyDelegate1 b = new MyDelegate1(p.AMethod);
Module 8: Delegates and Events 7

Calling a Delegate
Topic Objective
To explain how to call
delegates.
! Use a Statement Containing:
Lead-in
After a delegate is created, # The name of the delegate object
it can be passed to other
code that will call the # Followed by the parenthesized arguments to be passed
delegate. to the delegate

//
// given
given the
the previous
previous delegate
delegate declaration
declaration and
and
//
// instantiation,
instantiation, the
the following
following invokes
invokes MyClass'
MyClass'
//
// static
static method
method Hello
Hello with
with the
the parameter
parameter "World"
"World"

a("World");
a("World");

*ILLEGAL FOR NON-TRAINER USE**

After a delegate object is created, it can be passed to other code that will call the
delegate. For example, a server object may provide a method that a client
object calls to register a callback method for a specific event. The server will
invoke this callback method when that event occurs. Typically, the client
instantiates a delegate that refers to its callback method. The client passes the
callback delegate object as a parameter.
You can call a delegate object by using the name of the delegate, followed by
For Your Information the parenthesized arguments to be passed to the delegate. For example, using
Refer to the previous slide
on delegate declaration and
the declaration and instantiations of delegates a and b shown in the previous
instantiations. slide, the following lines invoke the static Hello method of the class MyClass
and the AMethod of the MyClass object p with the argument "World":
a("World");
b("World");
8 Module 8: Delegates and Events

Demonstration: Using Delegates

Topic Objective
To demonstrate using a
callback delegate.
Lead-in
In this demonstration, you
will use Microsoft Visual
Studio .NET to run code in
which a delegate to a light
object’s method is passed to
a switch object. When the
switch object’s state
changes, the switch object
calls the light object’s
method and passes its new
state.

*ILLEGAL FOR NON-TRAINER USE**

In this demonstration, you will use Microsoft Visual Studio® .NET to run code
Delivery Tip in which a delegate to a light object’s method is passed to a switch object.
Use Visual Studio .NET to
run the following code. Set
When the switch object’s state changes, the switch object calls the light
breakpoints or single step to object’s method and passes its new state.
illustrate the sequence of
events.
Module 8: Delegates and Events 9

using System;
For Your Information
As noted in C# Language-
namespace SwitchAndLight
Specific Syntax in this
module, delegate types with {
a void return value in C# public enum SwitchPosition {Up, Down};
cause the compiler to derive
the delegate class from the delegate void SwitchFlipped(SwitchPosition switchState);
MulticastDelegate class.
Therefore, the IL for this class Light
delegate demonstration {
code will show the private string name;
SwitchFlipped delegate
inheriting from the
public Light(string s)
System.MulticastDelegate
{
class.
name = s;
}

public void OnFlipCallback(SwitchPosition switchState)

{
if (switchState == SwitchPosition.Up)
{
Console.WriteLine("... {0} light is on",name);
}
else
{
Console.WriteLine("... {0} light is off",name);
}
}
}

class Switch
{
private SwitchPosition switchState =
SwitchPosition.Down;
private SwitchFlipped switchFlippedHandler = null;

public void ConnectToLight(SwitchFlipped lightHandler)

{
switchFlippedHandler = lightHandler;
}

public SwitchPosition SwitchState

{
get {return switchState;}
}

(Code continued on the following page.)

10 Module 8: Delegates and Events

public void OnFlip()

{
if (switchState == SwitchPosition.Down)
{
switchState = SwitchPosition.Up;
}
else
{
switchState = SwitchPosition.Down;
}
if (switchFlippedHandler != null)
{
switchFlippedHandler(switchState);
}
}
}

class TheApp
{
static void OnFlip(Switch aSwitch)
{
Console.WriteLine(
"Before flipping, the switch is: {0}",
aSwitch.SwitchState);
Console.WriteLine("Flipping switch ... ");
aSwitch.OnFlip();
Console.WriteLine(
"After flipping, the switch is: {0}\n\n",
aSwitch.SwitchState);
}

static void Main(string[] args)

{
Switch s = new Switch();
Light light1 = new Light("bathroom");
Light light2 = new Light("bedroom");

// connect switch and bathroom light by passing a

// delegate to the bathroom light's
// OnFlipCallback method to s
s.ConnectToLight(new
SwitchFlipped(light1.OnFlipCallback));
OnFlip(s);
OnFlip(s);

// connect switch and bedroom light by passing a

// delegate to the bedroom's light's
// OnFlipCallback method to s
s.ConnectToLight(new
SwitchFlipped(light2.OnFlipCallback));
OnFlip(s);
OnFlip(s);

}
}
}
Module 8: Delegates and Events 11

This code generates the following output:

Before flipping, the switch is: Down
Flipping switch ...
... bathroom light is on
After flipping, the switch is: Up

Before flipping, the switch is: Up

Flipping switch ...
... bathroom light is off
After flipping, the switch is: Down

Before flipping, the switch is: Down

Flipping switch ...
... bedroom light is on
After flipping, the switch is: Up

Before flipping, the switch is: Up

Flipping switch ...
... bedroom light is off
After flipping, the switch is: Down
12 Module 8: Delegates and Events

" Multicast Delegates

Topic Objective
To provide an overview of
the topics in this section.
! Multicast Delegate Scenario
Lead-in
If you change the state in ! Single vs. Multicast Delegates
one object, you may need to
broadcast that change to ! Creating and Invoking Multicast Delegates
multiple objects.
! C# Language-Specific Syntax
! Delegate Details

*ILLEGAL FOR NON-TRAINER USE**

If you change the state in one object, you may need to broadcast that change to
multiple objects. You can use multicast delegate objects to provide this
functionality; they can be composed together so that a single invocation invokes
all of their methods, just as a single light switch can turn on or off all lights
connected to that switch.

For Your Information

As noted in the C#
Language-Specific Syntax in
this module, delegate types
with a void return value in
C# cause the compiler to
derive the delegate class
from the MulticastDelegate
class.
Module 8: Delegates and Events 13

Multicast Delegate Scenario

Topic Objective 1 - Change in
4 - OnFlipCallback method
changes light1’s state
To illustrate the typical switch position Switch Object
multicast delegate use by invokes switch’s
Light1 Object
OnFlip method
using the common scenario
of a switch that controls two Light2 Object
light bulbs.
Lead-in
The following scenario of a OnFlip method OnFlipCallback
method
switch that controls two OnFlipCallback
lights illustrates the use of 2 - OnFlip method method
invokes multicast 3 - delegate1 invokes
multicast delegates. delegate1 light1’s OnFlipCallback
7 - OnFlipCallback
Invocation list method changes
light2’s state
Multicast
Multicastdelegate1
delegate1object
object

5 - delegate2 Multicast
Multicastdelegate2
delegate2object
object 6 - delegate2 invokes
is invoked light2’s OnFlipCallback

*ILLEGAL FOR NON-TRAINER USE**

To run the build slide, click In the light scenario, multicast delegate1 refers to the light1 object’s
through the lower-left button OnFlipCallback method, and multicast delegate2 refers to the light2 object’s
on the slide. OnFlipCallback method. Their composition logically represents an invocation
list, a list of methods that are executed when the delegate is invoked. In this
case, the invocation list consists of these two methods.
In the light switch scenario shown in the slide, the multicast delegate objects
The following scenario of a
switch that controls two
encapsulate references to two objects and two methods. When the switch is
lights illustrates the use of flipped:
multicast delegates. The 1. The switch object’s OnFlip method is invoked.
switch object models the
light switch, and the two 2. The OnFlip method invokes the multicast delegate1 object.
light objects model the two
electric lights. To provide
3. The multicast delegate1 object first invokes the light1 object’s
the capability to dynamically OnFlipCallback method.
connect, disconnect, and 4. The light1 object’s OnFlipCallback method changes the state of the light1
reconnect light object object.
methods to the switch
object, the switch object is 5. The multicast delegate1 object next invokes the multicast delegate2
dynamically connected to object.
the light objects by
6. The multicast delegate2 object invokes the light2 object’s
instantiating and composing
two multicast delegate OnFlipCallback method.
objects. 7. The light2 object’s OnFlipCallback method changes the state of the light2
object.

You can compose additional multicast delegates to allow the switch to control
additional lights.
14 Module 8: Delegates and Events

Single vs. Multicast Delegates

Topic Objective ! All Delegates Have an Invocation List of Methods That Are
To explain the difference Executed When Their Invoke Method is Called
between single-cast and ! Single-Cast Delegates: Derived Directly From
multicast delegates. System.MulticastDelegate
Lead-in # Invocation list contains only one method
When delegate declarations ! Multicast Delegates: Derived from System.MulticastDelegate
are compiled, the compiler
generates a new class, # Invocation list may contain multiple methods
which derives from two # Multicast delegates contain two static methods to add and remove
delegate classes provided references from invocation list: Combine and Remove
by the .NET Framework.
! Use GetInvocationList to Obtain an Invocation List as an Array of
Delegate References
! Use a Delegate’s Target and Method Properties to Determine:
# Which object will receive the callback
# Which method will be called

*ILLEGAL FOR NON-TRAINER USE**

When delegate declarations are compiled, the compiler, in effect, generates a
new class. The new delegate class derives from the System.MulticastDelegate
class that is provided by the .NET Framework.
All delegates have an invocation list, or linked list of delegates that are
executed when the invoke method is called. A delegate that derives from the
MulticastDelegate class may contain an invocation list with multiple delegates.
The MulticastDelegate class contains two static methods to add and remove
method references from an invocation list: Combine and Remove.
Combine is declared as follows:
public static Delegate Combine(
Delegate a,
Delegate b);

The method returns a new multicast Delegate object with an invocation list that
concatenates the invocation lists of a and b in that order.
Remove is declared as follows:
public static Delegate Remove(
Delegate source,
Delegate value);

The method returns a new Delegate object with an invocation list formed by
taking the invocation list of source and removing the last occurrence of value,
if value is found in the invocation list of source. If value is null or if value is
not found, then source is returned.
You can use the method GetInvocationList to obtain the invocation list as an
array of delegate references. You can also use the delegate’s Target and
Method properties to determine which object is to receive the callback and
which method is to be called. In the case of a static method, Target is null.
Module 8: Delegates and Events 15

Creating and Invoking Multicast Delegates

Topic Objective
To provide specific
examples of how to create //
// assign
assign to
to cc the
the composition
composition of
of delegates
delegates aa and
and bb
and invoke multicast cc == (MyDelegate2)Delegate.Combine(a,
(MyDelegate2)Delegate.Combine(a, b);
b);
delegates, and how to
iterate though an invocation //
// assign
assign to
to dd the
the result
result of
of removing
removing aa from
from cc
list to invoke specific dd == (MyDelegate2)Delegate.Remove(c, a);
(MyDelegate2)Delegate.Remove(c, a);
delegates.
//
// Iterate
Iterate through
through c'sc's invocation
invocation list
list
Lead-in //
This sample code shows // and
and invoke
invoke all
all delegates
delegates except
except aa
Delegate[]
Delegate[] DelegateList
DelegateList == c.GetInvocationList();
c.GetInvocationList();
how to create and invoke for
multicast delegates, and for (int i = 0;
(int i = 0; ii << DelegateList.Length;
DelegateList.Length; i++)
i++) {{
if
if (DelegateList[i].Target != aFoo1) {{
(DelegateList[i].Target != aFoo1)
how to iterate through an
((MyDelegate2)
((MyDelegate2) DelegateList[i])();
DelegateList[i])();
invocation list to invoke
}}
specific delegates.
}}

*ILLEGAL FOR NON-TRAINER USE**

The following sample code shows:
! How to create multicast delegate objects.
! How to write code to invoke delegates’ Combine and Remove methods.
! How to write code to iterate through an invocation list invoking all
delegates, except those delegates whose target is a specific object.
16 Module 8: Delegates and Events

using System;

public delegate void MyDelegate2();

public class Foo

{
public void Bar() {
Console.WriteLine("Bar invoked");
}
}

class Application {
public static void Main() {
Foo aFoo1 = new Foo();
Foo aFoo2 = new Foo();

MyDelegate2 a, b, c, d;

a = new MyDelegate2(aFoo1.Bar);
b = new MyDelegate2(aFoo2.Bar);

// assign to delegate c the composition of delegates a and b

c = (MyDelegate2)Delegate.Combine(a , b);

// assign to d the result of removing a from c

d = (MyDelegate2)Delegate.Remove(c , a);

// iterate through c's invocation list

// and invoke all delegates except those that target aFoo1
Delegate[] DelegateList = c.GetInvocationList();
for (int i = 0; i < DelegateList.Length; i++) {
if (DelegateList[i].Target != aFoo1) {
((MyDelegate2) DelegateList[i])();
}
}
}
}

The preceding code invokes the delegate that invokes object aFoo2’s Bar
method and outputs:
Bar invoked
Module 8: Delegates and Events 17

C# Language-Specific Syntax
Topic Objective
To present helpful
alternative C# syntax.
! C# Delegates That Return Void Are Multicast Delegates
Lead-in
Delegate types with a void ! In C#, Use the + and - Operators to Add and Remove
return value in C# cause the Invocation List Entries
compiler to derive the
delegate class from the # Less verbose than Combine and Remove methods
MulticastDelegate class.
MyDelegate
MyDelegate a, a, b,
b, c,
c, d;
d;
aa == new MyDelegate(Foo);
new MyDelegate(Foo);
bb == new
new MyDelegate(Bar);
MyDelegate(Bar);
cc == aa ++ b;
b; //
// Compose
Compose two
two delegates
delegates toto make
make another
another
dd == cc -- a;
a; //// Remove
Remove aa from
from the
the composed
composed delegate
delegate
aa +=
+= b;
b; //
// Add
Add delegate
delegate bb to
to a's
a's invocation
invocation list
list
aa -=
-= b;
b; //
// Remove
Remove delegate
delegate bb from
from a's
a's list
list

*ILLEGAL FOR NON-TRAINER USE**

Delegate types with a void return value in C# cause the compiler to derive the
delegate class from the MulticastDelegate class. You can also use these
delegates’ addition operator (+) and the subtraction operator (-) to invoke the
Combine and Remove methods for delegate composition and decomposition.
18 Module 8: Delegates and Events

Demonstration: Multicast Delegates

Topic Objective
To demonstrate how to use
the + and – operators to add
and remove methods.
Lead-in
You can add and remove
methods from the invocation
list of multicast delegates by
using the + and – operators.

*ILLEGAL FOR NON-TRAINER USE**

In this demonstration, you will learn how to add and remove methods from the
invocation list of multicast delegates by using the + and – operators.
using System;
Delivery Tip
Use Visual Studio .NET to
namespace Multicast_Delegates
run this code. Set
breakpoints or single-step to {
illustrate the sequence of
events. delegate void MyDelegate3(string s);

class MyClass
{
public static void Hello(string s) {
Console.WriteLine(" Hello, {0}!", s);
}

public static void Goodbye(string s) {

Console.WriteLine(" Goodbye, {0}!", s);
}

(Code continued on the following page.)

Module 8: Delegates and Events 19

public static void Main() {

MyDelegate3 a, b, c, d;
a = new MyDelegate3(MyClass.Hello);
b = new MyDelegate3(MyClass.Goodbye);
c = a + b; // Compose two delegates to make another
d = c - a; // Remove a from c to make another

Console.WriteLine("Invoking delegate a:");

a("A");
Console.WriteLine("Invoking delegate b:");
b("B");
Console.WriteLine("Invoking delegate c:");
c("C");
Console.WriteLine("Invoking delegate d:");
d("D");

Console.WriteLine("Adding b to a and invoking:");

a += b; // Add the b delegate to a
a("E");
Console.WriteLine("Removing b from a and invoking:");
a -= b; // Remove the b delegate from a
a("F");
}
}

This code generates the following output:

Invoking delegate a:
Hello, A!
Invoking delegate b:
Goodbye, B!
Invoking delegate c:
Hello, C!
Goodbye, C!
Invoking delegate d:
Goodbye, D!
Adding b to a and invoking:
Hello, E!
Goodbye, E!
Removing b from a and invoking:
Hello, F!
20 Module 8: Delegates and Events

Delegate Details
Topic Objective
To show how a delegate
declaration is handled by
the compiler. ! A Delegate Declaration Causes the Compiler to
Generate a New Class
Lead-in
When delegate declarations
//
// delegate
delegate void
void MyDelegate3(string
MyDelegate3(string val);
val);
are compiled, the compiler
generates a new class that
derives from class
class MyDelegate3
MyDelegate3 :: System.MulticastDelegate
System.MulticastDelegate {{
System.Delegate. public
public MyDelegate3(object
MyDelegate3(object obj,
obj, methodref
methodref mref)
mref)
:: base (obj, mref) { //...
base (obj, mref) { //...
}}
public
public void
void virtual
virtual Invoke(string
Invoke(string val)
val) {{ //...
//...
}}
};
};

*ILLEGAL FOR NON-TRAINER USE**

As previously noted in this module, when delegate declarations are compiled,
the compiler, in effect, generates a new class that derives from
System.Delegate. The new delegate class has two members: a constructor and
an Invoke method. The following class declaration resembles what the
compiler actually does:
// delegate void MyDelegate3(string val);

For Your Information class MyDelegate3 : System.MulticastDelegate {

There is no actual type
public MyDelegate3(object obj, methodref mref)
named methodref, but
having an instance of a type : base (obj, mref) {//...
that encapsulates a }
reference to a class method public void virtual Invoke(string val) {//...
resembles what the }
compiler actually does. }

The first member is a constructor: its first parameter is the delegate’s target
object, and its second parameter is a reference to a method. When a delegate
refers to a static method, the target object is null.
The Invoke method for the class MyDelegate3 indicates that delegate instances
of this class encapsulate methods that have a void return and a single string
parameter. When a delegate is invoked, the Invoke method is called with the
specified parameters.
Module 8: Delegates and Events 21

" Events
Topic Objective
To provide an overview of
the topics in this section.
! Event Scenario
Lead-in
An event is a way for a class ! Declaring an Event
to notify clients of that class
of a change in an object. ! Connecting to an Event
! Raising an Event
! .NET Framework Guidelines

*ILLEGAL FOR NON-TRAINER USE**

An event is a way for a class to notify clients of that class when some
interesting thing happens to an object. The most familiar use for events is in
graphical user interfaces. Typically the classes that represent controls in the
graphical user interface have events that are notified when a user manipulates
the control, as when a user clicks a button. However, the use of events is not
limited to graphical user interfaces. Events also allow an object to signal state
changes that may be useful to clients of that object. Events are an important
building block for creating classes that can be reused in many different
programs.
Delegates are particularly suited for implementing events. You can use the
.NET event mechanism to easily provide an object with type safe methods that
clients can call to register and deregister delegates to event handler methods.
When an event is raised, the event handler methods are called.
22 Module 8: Delegates and Events

Event Scenario
Topic Objective Mouse Object SoundMaker Object
To illustrate the .NET event MouseClicked field
mechanism through the MouseClicked
MouseClicked method
method
Invocation List:
scenario of a mouse clicked
event.
Lead-in multicast delegate object
This scenario of a mouse
object that notifies multicast delegate object
stopButton object
interested objects when a
mouse clicked event occurs MouseClicked
MouseClicked method
method
illustrates one use of add_MouseClicked method
delegates and events.
remove_MouseClicked method
OnMouseClicked
method

*ILLEGAL FOR NON-TRAINER USE**

To run the build slide, click This scenario of a mouse object that notifies interested client objects when a
through the lower-left button mouse click occurs illustrates one use of the .NET event mechanism. Client
on the slide. objects add and remove multicast delegate objects to the mouse object’s
invocation list. These delegates specify the event handler methods to be called
when a mouse click occurs. The mouse object code could be written to call a
predefined list of event handler methods. However, this approach does not offer
the flexibility to dynamically connect, disconnect, and reconnect methods to be
called when the mouse click event occurs. By using multicast delegate objects,
you can provide this flexibility.
In the mouse clicked event scenario that is shown in the slide, a mouse object
encapsulates code to monitor a hardware mouse:
1. The mouse object’s class uses the Microsoft Visual C#™ compiler event
keyword to have the compiler automatically create a private field named
MouseClicked that is used to store a reference to the invocation list of
delegates, and two public methods named add_MouseClicked and
remove_MouseClicked that are used to add and remove delegates to this
list. You can call these methods in Visual C# by using the += and -=
operators.
2. The mouse object’s class declares an OnMousedClicked method that is
called when a mouse click is detected. The OnMouseClicked method raises
the MouseClicked event by invoking the invocation list’s first delegate
object.
3. A user issues a command that causes sound to be generated whenever the
mouse is clicked. This command causes the mouse object’s
add_MouseClicked method to be called with a delegate object that points
to the soundMaker object’s MouseClicked method. This delegate is added
to the mouse object’s MouseClicked invocation list.
4. The mouse is clicked and the mouse object’s OnMouseClicked method is
called to raise the mouse clicked event.
Module 8: Delegates and Events 23

5. The OnMouseClicked method invokes the MouseClicked invocation list’s

delegate.
6. The delegate calls the SoundMaker object’s MouseClicked method and a
sound is generated.
7. A user then starts an application that operates a piece of machinery. The
application displays a Stop button on the screen that the user clicks to stop
the operation of the machinery. The application then instantiates a
stopButton object and calls the mouse object’s add_MouseClicked
method, passing a delegate object that refers to the stopButton object’s
MouseClicked method. This delegate is added to the mouse object’s
MouseClicked invocation list. The application then starts the machinery.
8. The mouse is clicked and the mouse object’s OnMouseClicked method is
called to raise the MouseClicked event.
9. The OnMouseClicked method invokes the MouseClicked invocation list’s
first delegate object. The delegate calls the SoundMaker object’s
MouseClicked method and a sound is generated.
10. The first delegate object invokes the second delegate object. The second
delegate object calls the stopButton object’s MouseClicked method. This
method checks the location of the mouse cursor and after determining that it
is located over the Stop button, halts the machinery.
11. The user then issues a command to terminate the application. The
application calls the mouse object’s remove_MouseClicked method,
passing a delegate object that refers to the stopButton object’s
MouseClicked method. This delegate is removed from the mouse object’s
MouseClicked invocation list.
24 Module 8: Delegates and Events

Declaring an Event
Topic Objective
To explain how to declare ! Declare the Delegate Type for the Event
events.
Lead-in ! Declare the Event
To declare an event inside a
class, you first must declare # Like the field of delegate type preceded by an event
a delegate type for the keyword
event.
//
// MouseClicked
MouseClicked delegate
delegate declared
declared
public
public delegate
delegate void
void MouseClickedEventHandler();
MouseClickedEventHandler();

public
public class
class Mouse
Mouse
{{
//
// MouseClicked
MouseClicked event
event declared
declared
public
public static
static event
event MouseClickedEventHandler
MouseClickedEventHandler
MouseClicked;
MouseClicked;
//...
//...
}}

*ILLEGAL FOR NON-TRAINER USE**

To declare an event inside a class, you first must declare a delegate type for the
event. The delegate type defines the set of arguments that are passed to the
method that handles the event.
Multiple events can share a delegate type, so you need only declare a delegate
type for an event if no suitable delegate type has already been declared. For
example, in the case of a MouseClicked event in which the method that
handles the event takes no arguments and returns void, the delegate is declared
as follows:
public delegate void MouseClickedEventHandler();

Next, the event itself is declared. You declare an event as you would declare a
field of delegate type, except that the keyword event follows the modifiers and
precedes the delegate type. Events usually are declared public, but any
accessibility modifier is allowed. The following code declares a class Mouse
with an event named MouseClicked:
public class Mouse
{
public static event MouseClickedEventHandler
MouseClicked;
//...
}
Module 8: Delegates and Events 25

When you declare an event, the compiler generates a private field that
references the end of a delegate invocation list. In the preceding example, a
private field named MouseClicked, which refers to delegates of type
MouseClickedEventHandler, is created.
The compiler also generates two public methods for clients to call to compose
and remove their delegate objects. In the preceding example, these public
methods would be named add_MouseClicked and remove_MouseClicked.
You can call these methods in C# by using the += and -= operators.
Because client access to the delegate invocation list is restricted to these
methods, the use of the event keyword not only makes the implementation of
events easier, it also prevents clients from accessing or raising the delegates of
other clients.
26 Module 8: Delegates and Events

Connecting to an Event
Topic Objective
To describe how to connect
to and disconnect from an
event.
! Connect by Combining Delegates
Lead-in ! Disconnect by Removing Delegates
From outside the class that
declared it, an event looks //
// Client’s
Client’s method
method to
to handle
handle the
the MouseClick
MouseClick event
event
like a field, but access to private void MouseClicked() { //...
private void MouseClicked() { //...
that field is restricted. }}
//...
//...

//
// Client
Client code
code to
to connect
connect to
to MouseClicked
MouseClicked event
event
Mouse.MouseClicked +=
Mouse.MouseClicked += newnew
MouseClickedEventHandler(MouseClicked);
MouseClickedEventHandler(MouseClicked);

//
// Client
Client code
code to
to break
break connection
connection to
to MouseClick
MouseClick event
event
Mouse.MouseClicked
Mouse.MouseClicked -= -= new
new
MouseClickedEventHandler(MouseClicked);
MouseClickedEventHandler(MouseClicked);

*ILLEGAL FOR NON-TRAINER USE**

From outside the class that declared it, an event looks like a field, but access to
that field is restricted. You can only add a delegate to an event or remove a
delegate from an event. In C#, you add and remove delegates by using the +=
and -= operators. To begin receiving event invocations, client code first creates
a delegate of the event type that refers to the method that should be invoked
from the event. Then, the client code uses the + and – operators to compose that
delegate with any other delegates to which the event might be connected. When
the client code is finished receiving event invocations, it removes its delegate
from the event by using the -= operator.
The following example shows how to connect to and disconnect from a
MouseClicked event:
public class aClient
{
// Client's method to handle the MouseClick event
private void MouseClicked() {
//...
}

//...

// code to connect to Mouse class' MouseClicked event

Mouse.MouseClicked += new
MouseClickedEventHandler(MouseClicked);

// code to break the connection to MouseClicked event

Mouse.MouseClicked -= new
MouseClickedEventHandler(MouseClicked);
//...
}
Module 8: Delegates and Events 27

Raising an Event
Topic Objective
To show when and how to
raise an event.
! Check Whether Any Clients Have Connected to
Lead-in This Event
After a class has declared
an event, it can treat that # If the event field is null, there are no clients
event like a field of the
indicated delegate type. ! Raise the Event by Invoking the Event’s Delegate

if
if (MouseClicked
(MouseClicked !=
!= null)
null)
MouseClicked();
MouseClicked();

*ILLEGAL FOR NON-TRAINER USE**

After a class has declared an event, it can treat that event like a field of the
indicated delegate type. The field will be null if no client has connected a
delegate to the event, or it will refer to a delegate that should be called when the
event is raised. Therefore, when an event is raised, you should first check for
null and then call the event. You can only raise an event from within the class
that declared the event.
if (MouseClicked != null) MouseClicked();
28 Module 8: Delegates and Events

.NET Framework Guidelines

Topic Objective
To introduce .NET ! Name Events with a Verb and Use Pascal Casing
Framework guidelines for
delegates and events. ! Use “Raise” for Events, Instead of “Fire”
Lead-in
You should follow .NET ! Event Argument Classes Extend System.EventArgs
Framework guidelines if you ! Event Delegates Return Void and Have Two Arguments
intend to use your
component in the .NET ! Use a Protected Virtual Method to Raise Each Event
Framework.
public
public class
class SwitchFlippedEventArgs
SwitchFlippedEventArgs :: EventArgs
EventArgs {{ //...
//...
}}

public
public delegate
delegate void
void SwitchFlippedEventHandler(
SwitchFlippedEventHandler(
object
object sender,
sender, SwitchFlippedEventArgs
SwitchFlippedEventArgs e);
e);

public
public event
event SwitchFlippedEventHandler
SwitchFlippedEventHandler SwitchFlipped;
SwitchFlipped;

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework includes guidelines on the delegate types that should be
used for events. If you are creating a component for use with the .NET
Framework, you should follow these guidelines:
! Consider naming events with a verb and use Pascal Casing. The Pascal
For Your Information Casing convention capitalizes the first character of each word. For example:
The Pascal Casing
convention capitalizes the
SwitchFlipped
first character of each word. Prefix pre- and post-event names by using the present and past tense. Do not
For example: BackColor use the BeforeXxx\AfterXxx pattern. For example, a close event that could
be canceled should have a Closing and Closed event. An event that
The camelCasing indicates that a control has been added should be declared as follows:
convention capitalizes the
first character of each word, public event ControlEventHandler ControlAdded;
except the first word. For
example: backColor ! Use “raise” for events, rather than “fired.”
When referring to events in documentation, use “an event was raised,”
instead of “an event was fired.”
! For the event’s delegate declaration, use a return type of void, two
parameters, an object source parameter named sender, and an e parameter
that encapsulates any additional information about the event. Delegates
should return void and have two arguments: the object that raised the event
and the event data object. Use names ending in EventHandler for the
event’s delegate, as in the following example:
public delegate void SwitchFlippedEventHandler(
object sender, SwitchFlippedEventArgs e);

The sender parameter represents the object that raised the event and called
the delegate. The sender parameter is always a parameter of type object,
even if you can employ a more specific type.
The state associated with the event is encapsulated in an instance of an event
class named e. Use an appropriate and specific event class for its type.
Module 8: Delegates and Events 29

! When necessary, event classes extend System.EventArgs and end in

EventArgs, as in the following example:
public class SwitchFlippedEventArgs : EventArgs {//...
}

For events that do not use any additional information, the .NET Framework
has already defined an appropriate delegate type: EventHandler, whose
argument is of the event base type EventArgs, as in the following example:
public delegate void EventHandler(
object sender, EventArgs e);

! Create an invoking method for the event.

Because events can only be raised from within the class that declared them,
derived classes cannot directly raise events that are declared within the base
class. Often it is appropriate to let the derived class raise the event. You can
do this by creating a protected invoking method for the event. By calling
this invoking method, derived classes can raise the event.
protected virtual void OnSwitchFlipped (//...) { //... }

For even more flexibility, you can declare the invoking method as virtual,
which allows the derived class to override it. This approach allows the
derived class to intercept the events that the base class is raising, possibly
doing its own processing of them.
For this reason, the .NET Framework guideline suggests that you create an
invoking method to raise an event that is a protected (family) virtual
method. However, if the class is sealed, the method should not be virtual
because the class cannot be derived from. Name the method OnEventName,
where EventName is the event being raised.
30 Module 8: Delegates and Events

The switch and light delegate scenarios in the preceding topics help to put these
guidelines in context. When a switch is flipped, the switch object raises a
SwitchFlipped event for connected light objects. In this case, the additional
SwitchFlipped event data indicates whether the switch is in the up or down
position:
public enum SwitchPosition {Up, Down};

// class to encapsulate switch data

public class SwitchFlippedEventArgs : EventArgs
{
private SwitchPosition position;

public SwitchFlippedEventArgs(SwitchPosition position) {

this.position = position;
}

public SwitchPosition Position {

get { return position; }
}
}

//delegate declaration
public delegate void SwitchFlippedEventHandler(
object sender, SwitchFlippedEventArgs e);

public class Switch

{
//event declaration
public event SwitchFlippedEventHandler SwitchFlipped;

// ProcessSwitchFlippedUp – called when switch flipped up

// to create an event argument object and raise the event
public void ProcessSwitchFlippedUp() {
SwitchFlippedEventArgs e =
new SwitchFlippedEventArgs(SwitchPosition.Up);
OnSwitchFlipped(e);
}

// ProcessSwitchFlippedDown – when switch flipped down

public void ProcessSwitchFlippedDown() {
SwitchFlippedEventArgs e =
new SwitchFlippedEventArgs(SwitchPosition.Down);
OnSwitchFlipped(e);
}

protected virtual void OnSwitchFlipped (

SwitchFlippedEventArgs e) {
if (SwitchFlipped != null) {
// call the delegate if non-null
SwitchFlipped(this, e);
}
}
//...
}
Module 8: Delegates and Events 31

When to Use Delegates, Events, and Interfaces

Topic Objective
To explain when to use ! Use a Delegate If:
delegates, events, and
interfaces. # You basically want a C-style function pointer
# You want single callback invocation
Lead-in
Delegates, interfaces, and # The callback should be registered in the call or at construction time, not
through an add method call
events all provide callback
functionality, but each has ! Use Events If:
specific usage # Client signs up for the callback function through an add method call
characteristics that make it
# More than one object will care
better suited to particular
situations. # You want end users to be able to easily add a listener to the notification in
the visual designer
! Use an Interface If:
# The callback function entails complex behavior,
such as multiple methods

*ILLEGAL FOR NON-TRAINER USE**

Delegates, interfaces, and events all provide callback functionality, but each has
specific usage characteristics that make it better suited to particular situations.
Use a delegate if:
! You basically want a C-style function pointer.
! You want single callback invocation.
! You want the callback function registered in the call or at construction time,
not through an add method call.

Use events if:

! Client code signs up for the callback prior to the occurrence of events,
typically through an add method call.
! More than one client object will care.
! You want end users to be able to easily add a listener to the notification in
the visual designer.

Use an interface if:

• The callback function entails complex behavior, as when more than one
callback method is invoked.
32 Module 8: Delegates and Events

Lab 8: Creating a Simple Chat Server

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will create
use delegates and events
with a simple chat server
application.

*ILLEGAL FOR NON-TRAINER USE**

Objectives
After completing this lab, you will be able to:
! Write code that uses the delegate class to create type-safe callbacks.
! Write code that uses the event keyword to simplify and improve the
implementation of a class that raises events.
! Write event code that conforms to the .NET Framework guidelines.

Lab Setup
Only solution files are associated with this lab. The solution files for this lab are
in the folder <install folder>\Labs\Lab08\Solution.

Scenario
In this lab, you will create a simple chat-style server to which multiple clients
can connect. When one client sends a string message to the server, the server
forwards the message to all registered clients that have not been specifically
excluded.
You should note that a real chat application would be based on a more scalable
and flexible design to connect client and servers, such as a publish-and-
subscribe design.

Estimated time to complete this lab: 60 minutes

Module 8: Delegates and Events 33

Exercise 1
Creating a Simple Chat Server Using Delegates
In this exercise, you will implement a simple chat server and clients by using
delegates.

Scenario
Each client will register a delegate with the server. Then, when a client sends a
message to the server, the server forwards the message to all specified clients.
This implementation uses delegates as a callback mechanism.

! Create a Visual Studio .NET project

• Open Visual Studio .NET and create a new C# Console Application project
named chat1 in <install folder>\Labs\Lab08.

! Create the chat server class

1. Create the chat server class and name it DChatServer.
2. Declare within the DChatServer class a delegate that will be used to invoke
the callback function in the client when a chat message arrives.
a. Name the delegate OnMsgArrived.
b. Declare this delegate public and reflect the callback function’s
signature. The callback’s signature is a void return value with a single
argument of type string.
3. Define a field to store the connected clients’ delegates by performing the
following steps.
a. Name the field onMsgArrived.
b. Make the field a private static reference to the type of the delegate,
OnMsgArrived.
4. Define the method that will be called by a client to connect that client to the
server by performing the following steps.
a. Name the method ClientConnect.
b. Declare the method public static void.
c. Include an argument of type OnMsgArrived.
d. Create the method’s implementation by using the delegate’s Combine
method to add this new delegate to the delegate stored in the
onMsgArrived invocation list.
As an alternative to the Combine method, you can use the += operator.
5. Define a method that will be called by a client to disconnect that client from
the server by performing the following steps.
a. Name the method ClientDisconnect.
b. Declare the method public static void.
c. Declare the method so that it has the same signature as ClientConnect.
d. Create the method’s implementation by using the delegate’s Remove
method to remove the delegate from the onMsgArrived invocation list.
As an alternative to the Remove method, you can use the -= operator.
34 Module 8: Delegates and Events

6. Define a method that will send a specified message to the connected clients,
with the possible exception of one client, by performing the following steps.
a. Name the method SendMsg.
b. Declare the method public static void.
c. Declare the method so that it takes two arguments: a string argument for
the message and an object argument for the excluded client.
d. Create the method’s implementation.
i. If the excluded client argument is null, invoke the multicast delegate
to send the message to all the clients.
ii. If the excluded client argument is not null, iterate through the
onMsgArrived delegate’s invocation list and invoke only those
delegates that do not match the excluded client argument.

! Create the chat client class

1. Create the chat client class and name it DChatClient.
2. Implement within the DChatClient class a callback method that the server
will invoke by a delegate when the server receives a chat message.
a. Name the method onMsgArrived.
b. Declare the method private void.
c. Declare the method so that it takes a single string argument.
d. Create the method’s implementation so that it prints the name of the
client along with the string argument to the console.
3. Add a constructor that will receive the name of the client as a parameter and
connect the client with the server.
a. Declare the constructor so that it takes a string argument that represents
the client’s name.
b. Create the constructor’s implementation.
i. Store the client’s name in a private field.
ii. Connect the client to the server by calling the server’s
ClientConnect method.
The call’s argument should be an instance of the delegate type
DChatServer.OnMsgArrived that was instantiated with the client’s
callback method: onMsgArrived.
Module 8: Delegates and Events 35

! Create the program’s main entry point

1. Name the class that contains the program’s standard Main entry point,
Application.
Typically, a Visual Studio .NET project creates the class with the Main
entry point for you. You may only need to rename this class.
2. Write to the console a line of text to indicate that the program is starting.
3. Instantiate three DChatClient objects, passing the client names “1”, “2”,
and “3” to the constructor.
4. Send a message to the server by invoking the static method SendMsg of the
DChatServer. The message should be sent to all clients.
5. Send a second message to all clients, except Client 2.
6. Write to the console a line of text to indicate that the program is finished.

! Compile and test the program

• Build the program and run it.
The output should resemble the following:
Demo start: Delegate Chat Server.
Msg arrived (Client 1): Hi to all clients
Msg arrived (Client 2): Hi to all clients
Msg arrived (Client 3): Hi to all clients
Msg arrived (Client 1): Hi to all clients except client 2
Msg arrived (Client 3): Hi to all clients except client 2
Demo stop: Delegate Chat Server.
36 Module 8: Delegates and Events

Exercise 2
Creating a Simple Chat Server Using Events
In this exercise, you will implement a simple chat server and clients by using
events and delegates. This implementation uses the event keyword, which hides
some of the low-level code details associated with delegates and prevents
clients from accessing or invoking the delegates of other clients.

Scenario
Each client will connect with the server’s “on message arrived” event. Then,
when one client sends a string message to the server, the server forwards the
message to all specified connected clients.

! Access the chat1 Visual Studio .NET project

• Open Visual Studio .NET and open the project named chat1, which you
created in Exercise 1, in <install folder>\Labs\Lab08. Open the previously
created C# source file and perform the following procedures.

! Create the event-based chat server class

1. Create a new chat server class and name it EChatServer.
2. Declare within the EChatServer class a delegate that will be used to invoke
the callback function in the client when a chat message arrives.
a. Name the delegate OnMsgArrived.
b. This delegate should be declared public and reflect the callback
function’s signature.
The callback’s signature is a void return value with a single argument of
type string.
3. Declare an event for the OnMsgArrived delegate type.
a. Name the event onMsgArrived.
b. Declare the event public static.
4. Define a method that will send a specified message to the connected clients,
with the possible exception of one client.
a. Name the method SendMsg.
b. Declare the method public static void.
c. Declare the method so that it takes two arguments: a string argument for
the message and an object argument for the excluded client.
d. Create the method’s implementation.
i. If the excluded client argument is null, invoke the multicast delegate
to send the message to all of the clients.
ii. If the excluded client argument is not null, iterate through the
onMsgArrived delegate’s invocation list and invoke only those
delegates that do not match the excluded client argument.
Module 8: Delegates and Events 37

! Create the event-based chat client class

1. Create a new chat client class and name it EChatClient.
2. Implement within the EChatClient class a callback method that the server
will invoke by a delegate when the server receives a chat message.
a. Name the method onMsgArrived.
b. Declare the method private void.
c. Declare the method so that it takes a single string argument.
d. Implement the method so that it prints the name of the client, together
with the string argument, to the console.
3. Add a constructor that will receive the name of the client as a parameter and
connect the client with the server.
a. Declare the constructor so that it takes a string argument that represents
the client’s name.
b. Create the constructor’s implementation.
i. Store the client’s name in a private field.
ii. Connect the client to the server by using the += operator to add a
new delegate instance to the EChatServer’s event.
The += operator’s right operand should be an instance of the delegate
type EChatServer.OnMsgArrived that was instantiated with the
client’s callback method, onMsgArrived.

! Extend the program’s main entry point by performing the following

procedures
1. Write to the console a line of text to indicate that the event chat portion of
the program is starting.
2. Instantiate three EChatClient objects, passing the client names “1”, “2”,
and “3” to the constructor.
3. Send a message to the server by invoking the static method SendMsg of the
EchatServer. You should send the message to all clients.
4. Send a second message to all clients except client 2.
5. Write to the console a line of text to indicate that event chat is finished.

! Compile and test the program

• Build the program and run it.
The output should resemble the following:
...

Demo start: Event Chat Server.

Msg arrived (Client 1): Hi to all clients
Msg arrived (Client 2): Hi to all clients
Msg arrived (Client 3): Hi to all clients
Msg arrived (Client 1): Hi to all clients except client 2
Msg arrived (Client 3): Hi to all clients except client 2
Demo stop: Event Chat Server.
38 Module 8: Delegates and Events

Exercise 3 (As Time Permits)

Conforming to the .NET Framework Guidelines
In this exercise, you will implement the simple chat program with events that
conform to the .NET Framework guidelines. Although the C# language allows
events to use any delegate type, the .NET Framework has stricter guidelines on
the delegate types that should be used for events. If you intend for your
component to be used with the .NET Framework, follow these guidelines.

Scenario
As in Exercise 2, each client connects with the server’s event. Then, when one
client sends a string message to the server, the server forwards the message to
all specified clients.
In this exercise, the delegate type will conform to the .NET Framework
guidelines. The delegate type will take two parameters, an object source
parameter, which indicates the source of the event, and an e parameter, which
encapsulates information about the event and, in this case, includes the string
message that generated the event.
In this exercise, you will also instantiate the chat server as an object.
Instantiating the chat server will allow you to invoke the connected client’s
delegates with a non-null object source parameter.

! Create the event class that will encapsulate the event’s state
1. Open Visual Studio .NET and open the project named chat1, which you
created in Exercise 1, in location <install folder>\Labs\Lab08. Open the
previously created C# source file and add the following code.
2. Create a new public class named MsgArrivedEventArgs that inherits from
EventArgs.
3. Declare within MsgArrivedEventArgs a private readonly field of type
string named message.
4. Declare a public constructor that takes a single string argument and stores it
in the field named message.
5. Add a property named Message that returns the value of message.
Module 8: Delegates and Events 39

! Create the guidelines-based chat server class

1. Create a new chat server class and name it GChatServer.
2. Declare within the GChatServer class a delegate that will be used to invoke
the function in the client when a chat message arrives.
a. Name the delegate MsgArrivedEventHandler.
b. This delegate should be declared public and reflect the guideline’s
signature of a void return value and two arguments of type object and
MsgArrivedEventArgs.
3. Declare an event for the MsgArrivedEventHandler delegate type.
a. Name the event MsgArrivedHandler.
b. Make the event public. Do not make it static.
4. Define a method that will send a specified message to the connected clients,
with the possible exception of one client.
a. Name the method SendMsg.
b. Declare the method public void.
c. Declare the method so that it takes two arguments: a string argument for
the message and an object argument for the excluded client.
d. Create the method’s implementation.
i. Instantiate an instance of the event class MsgArrivedEventArgs
with the message string.
ii. Invoke the OnMsgArrived method, which is implemented in the
next step.
5. Define the OnEvent method to raise the event.
a. Name the method OnMsgArrived. In accordance with the .NET
Framework guidelines declare the method protected virtual void with
two arguments of type MsgArrivedEventArgs and object.
b. Create the method’s implementation.
i. If the event’s field contains a non-null delegate list and the excluded
client argument is null, invoke the multicast delegate with the
appropriate arguments.
ii. If the event’s field contains a non-null delegate list and the excluded
client argument is not null, iterate through the MsgArrivedHandler
delegate’s invocation list and invoke only those delegates that do not
match the excluded client argument.
iii. If the event’s field contains a null delegate list, do nothing.
40 Module 8: Delegates and Events

! Create the guidelines-based chat client class

1. Create a new chat client class and name it GChatClient.
2. Implement within the GChatClient class a callback method that the server
will invoke by a delegate when the server receives a chat message.
a. Name the method onMsgArrived.
b. Declare the method private void.
c. Declare the method so that it takes an object and
MsgArrivedEventArgs arguments.
d. Create the method’s implementation so that it prints the name of the
client, the Message property of MsgArrivedEventArgs, and the server
object as a string to the console.
3. Add a constructor that will receive the name of the client and a reference to
the server, and will connect the client with the server.
a. Declare the constructor so that it takes a string argument that represents
the client’s name and a GChatServer argument that specifies the server
object.
b. Create the constructor’s implementation.
i. Store the client’s name in a private field.
ii. Store the server’s reference in a private field.
iii. Connect the client to the server by using the += operator to add a
new delegate instance to the GChatServer’s event.
The += operator’s right operand should be an instance of the delegate
type GChatServer.MsgArrivedEventHandler that was
instantiated with the client’s callback method: onMsgArrived.

! Extend the program’s main entry point by performing the following

procedures
1. Create an instance of the GChatServer object.
2. Write to the console a line of text to indicate that the guidelines-based chat
server class portion of the program is starting.
3. Instantiate three GChatClient objects, passing the client names “1”, “2”,
and “3” to the constructor.
4. Send a message to the server by invoking the SendMsg method of
GChatServer. The message should be sent to all clients.
5. Send a second message to all clients except client 2.
6. Write to the console a line of text to indicate that the guidelines-based event
chat is finished.
Module 8: Delegates and Events 41

! Compile and test the program

• Build the program and run it.
The guidelines-based event chat output should resemble the following:
...
Demo start: Guidelines Based Event Chat Server. Server:
GChatServer
Msg arrived (Client 1): Hi to all clients Server:
GChatServer
Msg arrived (Client 2): Hi to all clients Server:
GChatServer
Msg arrived (Client 3): Hi to all clients Server:
GChatServer
Msg arrived (Client 1): Hi to all clients except client 2
Server: GChatServer
Msg arrived (Client 3): Hi to all clients except client 2
Server: GChatServer
Demo stop: Guidelines Based Event Chat Server.
42 Module 8: Delegates and Events

Review
Topic Objective
To reinforce module
objectives by reviewing
key points. ! Delegates
Lead-in ! Multicast Delegates
The review questions cover
some of the key concepts ! Events
taught in this module.
! When to Use Delegates, Events, and Interfaces

*ILLEGAL FOR NON-TRAINER USE**

1. Write the code to declare a delegate that is named ProcessOrderCallback
for the following method:
static public bool ProcessOrder(int Quantity, string Item)
{ //...
}

public delegate bool ProcessOrderCallback (int Quantity,

string, string Item);

2. Write the code to call the following EnterOrder method, instantiating and
passing an instance of the ProcessOrderCallback delegate that refers to a
public static method that is named Foo in the public class Bar.
static public void EnterOrder(
ProcessOrderCallback processOrderCallback) { //...
};

EnterOrder( new ProcessOrderCallback(Bar.Foo) );

Module 8: Delegates and Events 43

3. Write the body of the static method EnterOrder that takes as an argument
an instance of the delegate that is declared in question 1. EnterOrder
outputs to the console strings to prompt for an item name and quantity and
reads in the user’s input. EnterOrder should invoke the callback delegate
with this information.
static public void EnterOrder(
ProcessOrderCallback processOrderCallback) {
Console.WriteLine("Enter Item Name:");
string name = Console.ReadLine();
Console.WriteLine("Enter Item Quanity:");
int quantity = Int32.Parse( Console.ReadLine() );
processOrderCallback(quantity, name);
}

4. Using the following declarations, write the code to add delegate b to a’s
invocation list.
delegate void MyDelegate();
MyDelegate a, b;
a = new MyDelegate(Bar1.Foo1);
b = new MyDelegate(Bar2.Foo2);
a += b;

5. Use the event keyword to write the code to declare a public static event for
a delegate type ProcessOrderEventHandler.
public static event ProcessOrderEventHandler
processOrderHandler;

6. Describe when you should use a delegate and when you should use an
event.
Use a delegate when:
• You want a C-style function pointer.
• You want single callback invocation.
• You want the callback function to be registered in the call or at
construction time, not in a separate add method.

Use an event when:

• Client code signs up for the callback prior to the occurrence of
events, typically through a separate add method.
• More than one client object will be affected.
THIS PAGE INTENTIONALLY LEFT BLANK
Module 9: Memory and
Resource Management

Contents

Overview 1
Memory Management Basics 2
Non-Memory Resource Management 12
Implicit Resource Management 13
Explicit Resource Management 26
Optimizing Garbage Collection 36
Lab 9: Memory and Resource Management 48
Review 55
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, place or event is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

 2001-2002 Microsoft Corporation. All rights reserved.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Module 9: Memory and Resource Management iii

Instructor Notes
Presentation: After completing this module, students will be able to:
125 Minutes
! Describe how garbage collection manages object memory.
Lab: ! Implicitly manage non-memory resources by using a destructor’s finalize
60 Minutes
code.
! Explicitly manage non-memory resources by using client-controlled
deterministic release of resources.
! Write code by using the temporary resource usage design pattern.
! Programmatically control the behavior of the garbage collection.
! Describe advanced garbage collection features.

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach
this module.

Required Materials
To teach this module, you need the Microsoft® PowerPoint® file 2349B_09.ppt.

Preparation Tasks
To prepare for this module, you should:
! Read all of the materials for this module.
! Review the animation.
! Practice the demonstrations.
! Complete the lab.
iv Module 9: Memory and Resource Management

Demonstrations
This section provides demonstration procedures that will not fit in the margin
notes or are not appropriate for the student notes.
The code for each of the following demonstrations is contained in one project
and is located in <install folder>\Democode\Mod09\
GARBAGE COLLECTION. In addition, the code for the individual
demonstrations is provided in the student notes.
Use the debugger to step through the code while you point out features and ask
students what they think will happen next.

Finalization
In this demonstration, you will show students how garbage collection handles
finalization and resurrection. In this demonstration, run the Introduction and
ResurrectionDemo methods.

The IDisposable Interface

In this demonstration, you will show students how to perform explicit resource
management by using the IDisposable interface. In this demonstration, run the
DisposeDemo method.

Weak References
In this demonstration, you will show students how garbage collection handles
weak references. In this demonstration, run the WeakRefDemo method.

Generations
In this demonstration, you will show students how garbage collection handles
generations. In this demonstration, run the GenerationDemo method.

Multimedia
This section lists the multimedia items that are part of this module. Instructions
for launching and playing the multimedia are included with the relevant slides.

Simple Garbage Collection

This animation will show students the Microsoft .NET Framework common
language runtime’s garbage collection process without finalization.

Garbage Collection
This animation will show students the .NET Framework common language
runtime garbage collection process, including finalization.
Module 9: Memory and Resource Management v

Module Strategy
Use the following strategy to present this module:
! Memory Management Basics
Students in your classes will probably use different approaches to memory
management. Begin with a brief review of different memory management
techniques that you or the students may have learned from experience.
Because students will need to adapt their programming practices to the
automatic memory management that is provided by the common language
runtime, it is important to mention other memory management techniques.
Compare and contrast manual memory management with the automatic
memory management that is provided by the common language runtime.
Outline the simple garbage collection process without the finalization details
and use the Simple Garbage Collection animation to help the students
understand the concept of the garbage collection process more easily.
Instructions for running the animations in this module are included in
Instructor Margin Notes.
! Non-Memory Resource Management
This topic is an introduction to handling non-memory resources implicitly
and explicitly. Tell students that the next two sections cover these areas in
detail. You should not spend much time on this slide.
! Implicit Resource Management
Introduce the finalization phase of the garbage collection process.
Emphasize that in C#, a destructor must be used for the finalization code.
The second animation, Garbage Collection, is more complex than the first.
It shows the garbage collection process with the finalization details.
Spend time discussing the drawbacks that are associated with finalization
and what to do if finalization is required. Show students how to deal with an
object that has been resurrected.
Use the Finalization demonstration to highlight how garbage collection
deals with finalization and resurrection.
! Explicit Resource Management
Show students how to perform explicit resource management by using the
IDisposable interface and Dispose method.
Discuss the temporary resource usage design pattern as an example of how
to allocate resources for temporary use.
! Optimizing Garbage Collection
Use the demonstrations that are provided to show how to optimize garbage
collection through weak references and generations.
In addition to discussing the programmatic optimizations that can be made
to the garbage collection process, briefly mention the use of performance
counters to monitor memory activity and the use of a multiprocessor system
to scale applications where there are garbage collection bottlenecks.
Module 9: Memory and Resource Management 1

Overview
Topic Objective
To provide an overview of
the module topics and
objectives.
! Memory Management Basics
Lead-in ! Non-Memory Resource Management
Objects in the Microsoft
.NET Framework use ! Implicit Resource Management
memory resources and may
use other resources, such ! Explicit Resource Management
as file handles. For software
! Optimizing Garbage Collection
to run properly, these
resources must be well
managed.

*ILLEGAL FOR NON-TRAINER USE**

Objects in the Microsoft® .NET Framework use memory resources and may use
other resources, such as file handles. For software to run properly, these
resources must be well managed. In other words, they must be properly
allocated and released.
After completing this module, you will be able to:
! Describe how garbage collection manages object memory.
! Implicitly manage non-memory resources by using a destructor’s finalize
code.
! Explicitly manage non-memory resources by using client-controlled
deterministic release of resources.
! Write code by using the temporary resource usage design pattern.
! Programmatically control the behavior of the garbage collection.
! Describe advanced garbage collection features.
2 Module 9: Memory and Resource Management

" Memory Management Basics

Topic Objective
To provide an overview of
the section topics.
! Developer Backgrounds
Lead-in
A major feature of the .NET ! Manual vs. Automatic Memory Management
Framework common
language runtime is that the ! Memory Management of .NET Framework Types
runtime automatically
handles the allocation and ! Simple Garbage Collection
release of an object’s
memory resources.

*ILLEGAL FOR NON-TRAINER USE**

A major feature of the .NET Framework common language runtime is that the
runtime automatically handles the allocation and release of an object’s memory
resources. In most cases, automatic memory management enhances code quality
and developer productivity without negatively impacting expressiveness or
performance.
Understanding how the .NET Framework facilitates resource management is
essential for writing correct and efficient code.
In this section, you will learn about memory management in the .NET
Framework, including simple garbage collection.
Module 9: Memory and Resource Management 3

Developer Backgrounds
Topic Objective
To discuss various
developer backgrounds with
regard to memory ! COM
management.
# Manually implement reference counting and handle
Lead-in circular references
Your experience with
memory management will ! C++
vary depending upon your
development background. # Manually use the new operator and delete operator
! Visual Basic
# Accustomed to automatic memory management

*ILLEGAL FOR NON-TRAINER USE**

Your experience with memory management will vary depending upon your
development background. In certain situations, you will need to adapt your
programming practices to the automatic memory management that is provided
by the common language runtime.

COM Developers
COM developers are accustomed to implementing reference counting as a
manual memory management technique. Each time an object is referenced, a
counter is incremented. When a reference to an object goes out of scope, the
counter is decremented. When an object’s reference count reaches zero, the
object is terminated and its memory is freed.
The reference counting scheme is the source of many bugs. If the reference
counting rules are not followed precisely, objects may be freed prematurely or
unreferenced objects may accumulate in memory.
Circular references are also a common source of bugs. A circular reference
occurs when a child object has a reference to a parent object, and the parent
object has a reference to the child object. Circular references prevent either
object from being released or destroyed. The only solution is for the parent and
child objects to agree on a fixed pattern of usage and destruction, such as where
the parent always deletes the child first.
When you develop applications in a managed language, the runtime’s garbage
collector eliminates the need for reference counting and, as a result, the bugs
that can arise from this manual memory management scheme.
4 Module 9: Memory and Resource Management

C++ Developers
C++ developers are accustomed to the tasks that are related to manual memory
management. In C++, when you allocate memory for an object by using the
new operator, you must release the object’s memory by using the delete
operator. This can lead to errors such as forgetting to release an object and
causing a memory leak, or attempting to access memory for an object that has
already been released.
When you develop applications by using the Managed Extensions for C++, or
another managed language, you do not have to use the delete operator to release
an object. The garbage collector does this for you automatically when the object
is no longer being used by the application.
C++ developers may be accustomed to avoiding the use of short-term objects
because of the associated cost of manually managing the memory for these
objects. For managed short-term objects that are created and then go out of
scope between collections, the cost of allocating and releasing memory is
extremely low.
In the .NET Framework, the garbage collector is actually optimized to manage
objects with short lifetimes. When you develop managed applications, it is
appropriate to use short-term objects in situations where they simplify your
code.

Visual Basic Developers

Microsoft Visual Basic® developers are accustomed to automatic memory
management. If you are a Visual Basic developer, the programming practices
with which you are familiar apply to the majority of the managed objects that
you create in the .NET Framework. However, you should take special note of
the suggested design pattern for a Dispose method to use when you create or
use objects that encapsulate unmanaged resources.
Module 9: Memory and Resource Management 5

Manual vs. Automatic Memory Management

Topic Objective
To introduce the advantages
of automatic memory ! Manual Memory Management
management in the .NET
Framework. # Programmer manages memory
Lead-in ! Common Problems
Manual memory
management requires that # Failure to release memory
you manage the allocation
and deallocation of blocks of # Invalid references to freed memory
memory.
! .NET Runtime Provides Automatic Memory Management
# Eases programming task
# Eliminates a potential source of bugs

*ILLEGAL FOR NON-TRAINER USE**

Manual memory management requires that you manage the allocation and
deallocation of blocks of memory. The NET Framework common language
runtime provides automatic memory management so that you are freed from
this time-consuming and difficult task.

Manual Memory Management

The following table provides examples of manual memory management in
different programming languages, C and C++, and in COM.
Language or
environment Example of manual memory management

C malloc and free functions

C++ new and delete operators
COM AddRef and Release reference counting methods

Automatic Memory Management in the .NET Framework

The .NET Framework common language runtime automatically handles
managed object memory and manages references to these objects, releasing
managed objects when they are no longer being used. This automatic memory
management eliminates the possibility of programming errors that can cause
memory leaks and the use of memory that has already been freed. With
automatic memory management, you no longer have to deal with complex bugs
that are associated with reference counting, circular reference leaks, or dangling
references.
6 Module 9: Memory and Resource Management

Memory Management of .NET Framework Types

Topic Objective
To explain how a value’s
type affects how the value is
managed in memory. ! Instances of Value Types Use Stack Memory
Lead-in # Allocation and deallocation are automatic and safe
In .the NET Framework, all
values have a type, which ! Managed Objects Are Reference Types and Use Heap
may be a value type or a Memory
reference type.
# Created by calls to the new operator
# Freed by garbage collection

*ILLEGAL FOR NON-TRAINER USE**

In the .NET Framework, all values have a type, which may be a value type or a
reference type. Each value’s type affects how that value is managed in memory.

Instances of Value Types

Instances of value types are stored in memory that is allocated on the stack.
Allocation and deallocation of memory occur automatically as follows:
! Allocation
Memory for an instance of a value type is created when the activation record
for its scope is pushed on to the stack.
! Deallocation
Memory is deallocated when the scope’s activation record, which contains
the value type instance, is popped from the stack.

Value types are always accessed directly. You cannot create a reference to a
value type, and therefore you cannot refer to a value instance that has been
deallocated. As a result, there is no danger of creating a dangling reference to a
value type.
Module 9: Memory and Resource Management 7

Instances of Reference Types

Managed objects are reference types, which you create by calls to the new
operator. The memory of these objects is allocated in the common language
runtime managed heap. You can access reference types only through a
reference to that storage. The use of references enables garbage collection to
track outstanding references to a particular instance and to free that object’s
heap memory when appropriate.
A managed object’s heap memory is only released through garbage collection
when there are no reachable references to that object. This mechanism ensures
that there will be no invalid references to the object’s freed memory and thus no
dangling references.
8 Module 9: Memory and Resource Management

Simple Garbage Collection

Topic Objective
To explain how simple
garbage collection works in
the .NET Framework. ! Simple Garbage Collection Algorithm
Lead-in # Wait until managed code threads are in a safe state
Garbage collection is
triggered when an # Build a graph of all reachable objects
application creates an
object, and there is not # Move reachable objects to compact heap
enough space left in the - Unreachable objects’ memory is reclaimed
heap to provide memory for
the object. # Update references to all moved objects
! Reference Cycles Are Handled Automatically

*ILLEGAL FOR NON-TRAINER USE**

Typically, garbage collection is triggered when an application creates an object,
and there is not enough space left in the heap to provide memory for the object.
Alternatively, you can invoke garbage collection programmatically. This
process is discussed in Optimizing Garbage Collection in this module.

The Garbage Collection Algorithm

Whether garbage collection occurs automatically or you invoke it
programmatically, the garbage collection algorithm is used to find any objects
in the heap whose memory can be reclaimed. Such objects include objects that
are no longer being used by the application. If garbage collection can reclaim
enough objects to free sufficient memory, memory for the new objects can be
allocated. Otherwise, an OutOfMemoryException is thrown.
For the sake of simplicity, this topic describes the simple garbage collection
process. The finalization phase and optimization details are discussed in
Implicit Resource Management in this module.

Simple Garbage Collection Process

Simple garbage collection uses the following process:
1. Waits until other managed threads reach a safe state, for example,
suspended.
The garbage collection process modifies managed objects and their
references. Therefore it must first wait until other managed threads are
suspended.
2. Builds a graph of all reachable objects.
3. Compacts the heap by moving reachable objects.
By moving reachable objects down in the heap, garbage collection reclaims
the space in the heap that was used by unreachable objects.
4. Updates all application references to moved objects.
Module 9: Memory and Resource Management 9

Building the Graph of Reachable Objects

Garbage collection accesses the collection of root references that are maintained
by the runtime. Each application has a logical collection of root references. The
collection contains all of the managed object references from global and static
objects and local variables that are currently on the stack and in CPU registers.
To build the graph of reachable objects, garbage collection performs the
following actions.
1. It adds all of the objects that are referenced by each root reference.
2. It recursively adds objects that are referenced by any added object.

Before an object is added to the graph, garbage collection checks to ensure that
the object is not already in the graph. This check prevents garbage collection
from entering an infinite loop that is caused by circular references.
At the end of the process, any object that is not in the reachable object graph is
considered unreachable and therefore garbage.

Reference Cycles Handled Automatically

An object is reachable only if there is a path from a root reference to that object.
Therefore, reference cycles between unreachable objects will not prevent the
objects’ memory from being released by the garbage collection process. For
example, if A references B and B references A, then both objects will be
garbage collected when they are no longer reachable from a root reference.
10 Module 9: Memory and Resource Management

Multimedia: Simple Garbage Collection

Topic Objective
To illustrate the .NET
Framework garbage
collection process.
Lead-in
This animation illustrates the
.NET Framework common
language runtime’s garbage
collection process.

*ILLEGAL FOR NON-TRAINER USE**

To launch the animation, This animation illustrates the .NET Framework common language runtime
click the button in the lower garbage collection process.
left corner of the slide. To
play the animation, click the
Simplified Garbage
Note Compiler optimization is disabled in this scenario to prevent an object
Collection button at the top from becoming eligible for garbage collection earlier than would be expected.
of the screen, and then click Otherwise, the compiler could optimize away assignments to local variables
the play button in the lower that are never observed by a later read. This optimization could result in an
left corner of the screen. object being subject to garbage collection before its reference is assigned to
null.

! The common language runtime allocates memory resources for reference

type objects in the section of the application’s memory that is called the
managed heap.
! When there is insufficient space in the managed heap, the common language
runtime executes the garbage collection algorithm to remove objects that are
no longer being used by the application.
Module 9: Memory and Resource Management 11

The steps of the algorithm are as follows:

1. After all other managed threads reach a safe state, for example suspended,
garbage collection builds a graph of all of the objects that are reachable
from the root references.
2. Before an item is added to the graph, a check is made to ensure that the
object is not already in the graph.
This check ensures that circular references are handled without garbage
collection entering an infinite loop.
3. After all of the root references and added objects have been processed, any
objects that are not in the graph are not reachable by the application.
The memory for these objects can be reclaimed when the heap is
compacted.
4. The remaining objects are moved down in the heap to fill the gaps.
5. The garbage collection process must then update all references to the moved
objects.
12 Module 9: Memory and Resource Management

Non-Memory Resource Management

Topic Objective
To provide an overview of
non-memory resource
management, which is ! Implicit Resource Management
discussed in the following
! Explicit Resource Management
topics.
Lead-in
Managed objects
sometimes encapsulate
control over resources that
are not managed by the
runtime.

*ILLEGAL FOR NON-TRAINER USE**

Managed objects sometimes encapsulate control over resources that are not
For Your Information managed by the runtime. Examples of these non-memory resources include
This topic is an introduction
to handling non-memory
window handles, file handles, and database connections.
resources implicitly and You need implicit and explicit ways to free these resources. Garbage collection
explicitly. Tell students that
provides implicit resource management of an object by calling the object’s
the next two sections cover
these areas in detail. You
finalize code.
should not spend much time The client of an object provides explicit resource management by calling the
on this slide.
Dispose method on the IDisposable interface of the object when the client is
finished using the object.
Module 9: Memory and Resource Management 13

" Implicit Resource Management

Topic Objective
To provide an overview of
the section topics.
! Finalization
Lead-in
The .NET Framework ! Garbage Collection with Finalization
common language runtime
provides the means for ! Finalization Guidelines
notifying an object before it
is destroyed so that it can ! Controlling Garbage Collection
clean up and release non-
memory resources.

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework common language runtime provides the means for
notifying an object before it is destroyed so that it can clean up and release non-
memory resources.
In this section, you will learn how to take advantage of this feature.
14 Module 9: Memory and Resource Management

Finalization
Topic Objective
To define and describe
finalization in garbage
collection. ! Finalize Code Called by Garbage Collection
Lead-in ! In C#, the Finalize Code Is Provided by a Destructor
Implicit management of
resources ensures that an ! Use C# Destructor to Implicitly Close a FileStream
object can properly clean up
its resources at some time class
class Foo
Foo {{
in the future when there are private
private System.IO.FileStream
System.IO.FileStream fs;
fs;
no longer any valid //...
//...
references to the object. public
public Foo()
Foo() {{
fs
fs == new
new System.IO.FileStream(
System.IO.FileStream(
"bar",
"bar", FileMode.CreateNew);
FileMode.CreateNew);
}}
~Foo()
~Foo() {{ fs.Close();
fs.Close(); }}
}}

*ILLEGAL FOR NON-TRAINER USE**

Implicit management of resources ensures that an object can properly clean up
its resources at some time in the future when there are no longer any valid
references to the object.
If an object provides finalize code in its destructor, the garbage collection
process calls this code when there are no longer any valid references to the
object. This phase of garbage collection is referred to as finalization.
Finalization allows an object to properly cleanup before its memory resources
are freed.

Using a Destructor for Finalization

In C#, the Finalize method is not directly accessible, and you cannot call or
override the Finalize method. You must place code to be executed during
finalization inside a C# destructor. The syntax for a C# destructor is the tilde
operator (~), followed by the class name and a block of statements that will be
executed during finalization. The following example shows the C# destructor
syntax for a class named Foo.
~Foo() {
// ... perform some cleanup operation here
}
Module 9: Memory and Resource Management 15

This code implicitly translates to the following:

protected override void Finalize() {
try {
// ... do something
}
finally {
base.Finalize();
}
}

Destructors are not inherited. When the finalization code of an object is

executed and the object is destructed, the destructors in the inheritance chain of
that object are called in order, from the most derived destructor to the least
derived destructor.

Differences Between C# and C++ Destructors

C# destructors and C++ destructors differ in several important ways, as shown
in the following table.
Destructor Characteristics

C# destructors Execute non-deterministically

Automatically invoked at any time after an object becomes eligible
for garbage collection
Not guaranteed to run in any specific order, even if one object
contains or refers to another
Cannot be invoked explicitly
C++ destructors Execute deterministically
Run in the order they are called
Can be invoked explicitly

An Example of Implicit Resource Management

A class Foo has a constructor that creates a FileStream. To ensure that the
buffer of the FileStream object is properly flushed, the class Foo provides
implicit management of the resource through destructor code that closes the
FileStream, as shown in the following code:
class Foo {
private System.IO.FileStream fs;
//...
public Foo() {
fs = new System.IO.FileStream("bar", FileMode.CreateNew);
}
~Foo() { fs.Close(); }
}

Implicit management of resources may not be adequate in all circumstances. In

the preceding example, full access by other objects to the file that is opened by
a Foo object may be delayed for an indeterminate amount of time after the Foo
object no longer needs the resource. Therefore, you typically need to use an
explicit form of resource management. For more information about explicit
resource management, see Explicit Resource Management in this module.
16 Module 9: Memory and Resource Management

Garbage Collection with Finalization

Topic Objective
To describe the initial
process of garbage ! Runtime Maintains a List of Objects That Require Finalization
collection with finalization. # Finalization queue
Lead-in ! Garbage Collection Process Invoked
Finalization adds to the
complexity and increases ! Unreachable Objects Requiring Finalization
performance overhead of
# References added to freachable queue
the basic garbage collection
process, as it was described # Objects are now reachable and not garbage
in Simple Garbage
Collection in this module. ! Move Reachable Objects to Compact the Heap
# Unreachable objects' memory is reclaimed
! Update References to All Moved Objects

*ILLEGAL FOR NON-TRAINER USE**

Finalization adds to the complexity and increases performance overhead of the
basic garbage collection process, as it was described in Simple Garbage
Collection in this module.
The .NET Framework common language runtime maintains a list of managed
objects that require finalization. This list is known as the finalization queue and
is used during garbage collection to provide implicit resource management.
Garbage collection is typically invoked when the creation of a new object
requires more space in the managed heap than is currently available.
After waiting for all other managed threads to be suspended, garbage collection
with finalization proceeds as follows:
1. Garbage collection builds a graph of all reachable objects, as described in
Simple Garbage Collection in this module.
Any managed object that is not in the graph is unreachable.
2. Garbage collection checks the finalization queue to see if an unreachable
object requires finalization.
If an unreachable object requires finalization, it is removed from the
finalization queue, and a reference to the object is placed in the freachable
(pronounced F-reachable) queue. The freachable queue is part of the root
references of an application. The object is therefore now considered
reachable and is no longer garbage.
3. Garbage collection compacts the heap and updates references to all moved
objects.
At this point, the memory resources for the unreachable objects have been
freed.
4. Garbage collection allows the application to continue normal operation.

At this point, the finalization phase of the garbage collection process can
commence on a separate thread.
Module 9: Memory and Resource Management 17

Garbage Collection with Finalization (continued)

Topic Objective
To describe the latter part of
the process of garbage
collection with finalization. ! Finalize Thread Runs
Lead-in # Executes freachable objects' Finalize methods
After the memory resources
for the unreachable objects # References removed from freachable queue
are freed and the application
has continued normal # Unless resurrected, objects are now garbage
operation, the finalization
phase of garbage collection
# May be reclaimed next time garbage collection occurs
commences on a separate
thread.

*ILLEGAL FOR NON-TRAINER USE**

After the memory resources for the unreachable objects are freed and the
application has continued normal operation, the finalization phase of garbage
collection commences on a separate thread.

The Finalization Phase

As the application runs, a special runtime thread removes references to objects
from the freachable queue and calls the finalize code of those objects.
Therefore, it is important that this code does not depend upon the identity of the
thread. For example, the method should not depend on thread local storage.
After an object has been finalized and removed from the freachable queue, it
becomes unreachable again as long as that object has not been resurrected. An
object is resurrected if it becomes reachable from an application root after
previously being unreachable.
However, the object’s memory resources are not freed at this time. The
reclamation of the object’s memory resources must wait until garbage
collection occurs next.
18 Module 9: Memory and Resource Management

Resurrection
Resurrection of an object occurs when a previously unreachable object becomes
reachable from an application root during finalization. For example, the finalize
code for an object may assign to a global or static variable a reference to the
object itself. The object is now reachable and is not subject to garbage
collection.

Issues with Resurrection

You should avoid resurrection when possible because the object’s finalize code
has been called and may have released resources that are required for the
object’s proper operation, even if the object’s memory is valid.
For example, when the destructor of the Foo class that was shown in An
Example of Implicit Resource Management in this module executes its
finalization code, the file will close, and the other methods of Foo that require
an open FileStream may not be able to successfully complete.
In addition, when a resurrected object becomes unreachable sometime in the
future, its finalize code will not be called unless the object has called the
GC.ReRegisterForFinalize method.
You should also note that even if the finalize code of a class does not resurrect
an object, that object may still be resurrected, as when another object that refers
to the object is resurrected. Thus, all objects should be able to handle
resurrection. For more information about resurrection and finalization, see
Controlling Garbage Collection in this module.
Module 9: Memory and Resource Management 19

Multimedia: Garbage Collection

Topic Objective
To illustrate how garbage
collection, including
finalization, works.
Lead-in
This animation illustrates the
.NET Framework common
language runtime garbage
collection process, including
finalization.

To launch the animation,

click the button in the lower
left corner of the slide. To
play the animation, click the
play button in the lower left
corner of the screen.

*ILLEGAL FOR NON-TRAINER USE**

This animation illustrates the .NET Framework common language runtime
garbage collection process, including finalization.

Note Compiler optimization is disabled in this scenario to prevent an object

from becoming eligible for garbage collection earlier than would be expected.
Otherwise, the compiler could optimize away assignments to local variables
that are never observed by a later read. This optimization could result in an
object being subject to garbage collection before its reference is assigned to
null.

In this animation, you will learn that:

! The .NET Framework common language runtime allocates memory
resources for objects in the section of the application’s memory that is
called the managed heap.
! The finalization queue holds references to objects whose classes require
finalization.
! The freachable queue is a special kind of root reference whose entries are
references to objects that are ready to have their finalize code invoked. An
freachable reference keeps the object alive.
! The nondeterministic release of memory and non-memory resources is
another significant difference between .NET Framework and C++
destructors.
20 Module 9: Memory and Resource Management

Finalization Guidelines
Topic Objective
To alert students to issues
that are associated with
! Avoid Finalization and Destructors If Possible
finalization.
# Performance costs
Lead-in
This topic provides # Complexity
guidelines for handling
# Delay of memory resource release
finalization.
! If You Require Finalization, Finalize Code Should:
# Avoid calling other objects
# Avoid making assumptions about thread ID
! Classes with Finalization Should:
# Avoid making references to other objects

*ILLEGAL FOR NON-TRAINER USE**

This topic provides guidelines for handling finalization. To avoid problems that
result from the .NET Framework’s nondeterministic ordering of calls to finalize
code, you may need to use explicit resource management in addition to careful
design.

Avoid Finalization if Possible

You should only implement finalization, or implement a destructor in C#, on
classes that require finalization. If your class has only managed references and
does not have to manage non-memory resources, you should not implement
finalize code. Finalization adds overhead and complexity, and delays the
reclamation of an object’s memory resources.

Implementing Finalization
If you must implement finalization, you should obey the following guidelines:
! Avoid calling other objects in finalization code.
In your finalization code, free any external resources that your object is
holding on to. However, you should avoid calling other objects, for
example, contained objects, because their finalize code may have already
been called. The .NET Framework common language runtime does not
specify any order on its invocation of the finalize code of freachable objects.
Therefore, if an object of type Foo refers to an object of type Bar, you
cannot know whether the finalize code of Foo will be called before or after
the finalize code of Bar. This nondeterminism may cause problems if the
finalize code of Foo calls a method in Bar that requires a resource that is
released by Bar in its finalize code.
! Avoid assumptions about thread ID.
As previously noted, finalization code should not make any assumptions
about the thread ID.
Module 9: Memory and Resource Management 21

! Ensure that the Finalize code of your base class is called.

This call is performed automatically by the C# destructor syntax.
! Avoid references to other objects.
A class that requires finalization should avoid references to other objects
because a finalizable object will prolong its own lifetime and the lifetime of
objects that it references. If possible, you should factor such classes into the
following two classes:
• One class that contains the resource that requires management and has
the finalize code but has no other object references.
• A second class that holds the references to other objects but has no
finalize code.
22 Module 9: Memory and Resource Management

Controlling Garbage Collection

Topic Objective
To introduce techniques to ! To Force Garbage Collection
control garbage collection.
void
void System.GC.Collect();
System.GC.Collect();
Lead-in
The System.GC class of the ! To Suspend Calling Thread Until Thread’s Queue of Finalizers
.NET Framework contains Is Empty
methods that can be used to void
void System.GC.WaitForPendingFinalizers();
System.GC.WaitForPendingFinalizers();
control the garbage
collection process. ! To Allow a Finalized Resurrected Object to Have Its Finalizer
Called Again

void
void System.GC.ReRegisterForFinalize(object
System.GC.ReRegisterForFinalize(object obj);
obj);

! To Request the System Not to Call the Finalizer Method

void
void System.GC.SuppressFinalize(object
System.GC.SuppressFinalize(object obj);
obj);

*ILLEGAL FOR NON-TRAINER USE**

The System.GC class of the .NET Framework contains methods that can be
used to control garbage collection. The Collect method with no arguments
forces the collection of all generations, as in the following code:
void System.GC.Collect();

For more information about generations, see Generations in this module.

Finalizers are run on a separate thread of execution. When the
WaitForPendingFinalizers method is called, the current thread is suspended
until the queue of finalizers that are waiting to run is empty. Because the
running of finalizers may trigger another garbage collection, which may, in
turn, re-queue new finalizers, there is no guarantee that the call to
WaitForPendingFinalizers will terminate.
void System.GC.WaitForPendingFinalizers();

After the garbage collection process calls an object’s finalize code, garbage
collection assumes that there is no need to call it again. However, if an object is
resurrected, the ReRegisterForFinalize method may be called to force garbage
collection to call the object’s finalize code again the next time the object is
destroyed. Note that if ReRegisterForFinalize is called multiple times, the
object’s finalize code will also be called multiple times.
void System.GC.ReRegisterForFinalize(object obj);

If an object that has finalize code no longer requires finalization to manage its
resources, the object may call the SuppressFinalize method to improve
performance. For example, an object that supports explicit resource
management should call the SuppressFinalize method when it releases its
resources, as in the following code:
void System.GC.SuppressFinalize(object obj);
Module 9: Memory and Resource Management 23

Demonstration: Finalization
Topic Objective
To demonstrate how
garbage collection handles
finalization and resurrection.
Lead-in
This demonstration shows
how garbage collection
handles finalization and
resurrection.

*ILLEGAL FOR NON-TRAINER USE**

This demonstration shows how garbage collection handles finalization and
resurrection.
// This method demonstrates how the GC works.
For Your Information private static void Introduction() {
Use the debugger to step
Display(0,
through the code while you
point out features and ask "\n\nDemo start: Introduction to Garbage Collection.", +1);
students what they think will
happen next. In this section // Create a new DerivedObj in the managed heap
run the Introduction and // Note: Both BaseObj and DerivedObj constructors are called
ResurrectionDemo DerivedObj obj = new DerivedObj("Introduction");
methods.
obj = null; // We no longer need this object

// The object is unreachable so forcing a GC causes it to be

// finalized.
Collect();

// Wait for the GC's Finalize thread to finish

// executing all queued Finalize code.
WaitForFinalizers();

// NOTE: The GC calls the most-derived (farthest away from

// the Object base class) destructor.
// A C# destructor automatically
// calls its base class destructor.

(Code continued on the following page.)

24 Module 9: Memory and Resource Management

// This is the same test as above with one slight variation

obj = new DerivedObj("Introduction");
// obj = null; // Variation: this line is commented out
Collect();
WaitForFinalizers();
// If compiler optimization was turned on:
// Notice that we get identical results as above:
// the destructor’s Finalize code
// runs because the just in time compiler’s optimizer
// knows that obj is not referenced later in this function

// Now we explicitly release the object and the destructor’s

// Finalize code is run.
// If compiler optimization was turned off
// we now see the finalization called otherwise nothing.
obj = null;
Collect();
WaitForFinalizers();
Display(-1,
"Demo stop: Introduction to Garbage Collection.", 0);
}

// Resurrection

// This reference is accessed in the ResurrectObj.Finalize

// code and is used to create a strong reference to an
// object (resurrecting it).
static public ResurrectObj ResObjHolder; // Defaults to null

// This method demonstrates how the GC supports resurrection.

// NOTE: Resurrection is discouraged.
private static void ResurrectionDemo() {
Display(0, "\n\nDemo start: Object Resurrection.", +1);

// Create a ResurrectObj
ResurrectObj obj = new ResurrectObj("Resurrection");

// Destroy all strong references to the new ResurrectionObj

obj = null;

// Force the GC to determine that the object is unreachable.

Collect();
WaitForFinalizers();
// You should see the Finalize code called.

// However, the ResurrectObj's Finalize code

// resurrects the object keeping it alive.
// It does this by placing a
// reference to the dying-object in Application.ResObjHolder

// You can see that ResurrectObj still exists because

// the following line doesn't raise an exception.
ResObjHolder.Display("Still alive after Finalize called");

(Code continued on the following page.)

Module 9: Memory and Resource Management 25

// Prevent the ResurrectObj object from resurrecting

// itself again,
ResObjHolder.SetResurrection(false);

// Now, let's destroy this last reference to the

// ResurrectObj
ResObjHolder = null;

// Force the GC to determine that the object is unreachable.

Collect();
WaitForFinalizers();
// You should see the Finalize code called.
Display(-1, "Demo stop: Object Resurrection.", 0);
}
26 Module 9: Memory and Resource Management

" Explicit Resource Management

Topic Objective
To provide an overview of
the section topics.
! The IDisposable Interface and the Dispose Method
Lead-in
Your classes should provide ! Temporary Resource Usage Design Pattern
an explicit and an implicit
way to free resources.

*ILLEGAL FOR NON-TRAINER USE**

Typically, your classes should provide an explicit and an implicit way to free
resources. A class provides explicit control by having a method that a client of
the object will call when the client has finished using the object.
In this section, you will learn how to perform explicit resource management by
using the IDisposable interface and Dispose method, and how to allocate
resources for temporary use.
Module 9: Memory and Resource Management 27

The IDisposable Interface and the Dispose Method

Topic Objective
To explain how to use the
IDisposable interface and
the Dispose method when ! Inherit from the IDisposable Interface
working with explicit
! Implement the Dispose Method
resource management.
Lead-in ! Follow the .NET Framework SDK’s Design Pattern
Classes that contain non-
memory resources should class
class ResourceWrapper
ResourceWrapper :: IDisposable
IDisposable
provide explicit resource {{
management by inheriting //
// see
see code
code example
example for
for details
details
from the IDisposable }}
interface and implementing
its Dispose method.

*ILLEGAL FOR NON-TRAINER USE**

Classes that contain non-memory resources should provide explicit resource
management by inheriting from the IDisposable interface and implementing its
Dispose method. A type’s Dispose method should release all of the resources
that it owns. It should also release all resources owned by its base types by
calling its parent type’s Dispose method. The parent type’s Dispose method
should release all resources that it owns and in turn call its parent type’s
Dispose method, propagating this pattern through the hierarchy of base types.
To ensure that resources are always cleaned up appropriately, a Dispose method
should be safely callable multiple times and should never throw an exception.
A Dispose method should call the GC.SuppressFinalize method for the object
For Your Information it is disposing. If the object is currently on the finalization queue,
The IDisposable interface
and Dispose method are
GC.SuppressFinalize prevents its Finalize code from being called. Remember
important topics that the that executing Finalize code is costly to performance. If your Dispose method
students will need to know has already done the work to clean up the object, then it is not necessary for the
to do the lab. The garbage collector to call the object’s Finalize code.
ResourceWrapper design
pattern should be discussed The following code example from the .NET Framework Software Development
in detail. Kit (SDK) illustrates one possible design pattern for implementing a Dispose
method for classes that encapsulate unmanaged resources. You may find this
pattern convenient to use because it is implemented throughout the .NET
Framework. However, this is not the only possible implementation of a Dispose
method. The base class implements a public Dispose method that can be called
by users of the class. The Dispose method in turn calls the appropriate virtual
Dispose method, depending upon the identity of the caller. The appropriate
cleanup code for the object is executed in the virtual Dispose method. The base
class provides a destructor as a safeguard in the event that Dispose is not called,
as in the following example of the ResourceWrapper design pattern:
28 Module 9: Memory and Resource Management

// Design pattern for a base class

public class BaseResource: IDisposable
{
// Pointer to an external resource.
private IntPtr handle;
// Pointer to a managed object resource this class uses.
private Component Components;
// To track whether Dispose has been called.
private bool disposed = false;

// Constructor for the BaseResource Object.

public BaseResource()
{
handle = // Insert code here to allocate on the
// unmanaged side.
Components = new Component();
}

// Implement IDisposable.
public void Dispose()
{
Dispose(true);
// Take yourself off of the Finalization queue.
GC.SuppressFinalize(this);
}

// The virtual Dispose(bool) method is called by:

// IDisposable.Dispose() with disposing = true
// and by Finalize/C# Destructor with disposing = false
protected virtual void Dispose(bool disposing)
{
// Check to see if Dispose has already been called.
if(!this.disposed)
{
// If IDisposable.Dispose was called,
// dispose all managed resources.
if(disposing)
{
// Free other state (managed objects)
Components.Dispose();
}
// If Finalize or IDisposable.Dispose,
// free your own state (unmanaged objects)
this.disposed = true;
Release(handle);
handle = IntPtr.Zero;
// Set any large fields to null
}
}

// Use C# destructor syntax for finalization code.

// This destructor will run only if the Dispose method
// does not get called.
// It gives your base class the opportunity to finalize.

(Code continued on the following page.)

Module 9: Memory and Resource Management 29

~BaseResource()
{
Dispose(false);
}

// Allow your Dispose method to be called multiple times,

// but throw an exception if a method requires resources
// that were released because an object has been disposed.

public void DoSomething()

{
// This method requires resources that may have been
// disposed,
// check to see if it has been disposed.
if(this.disposed)
{
throw new ObjectDisposedException("BaseResource");
}
}
}

// Design pattern for a derived class

public class MyResourceWrapper: BaseResource
{
private bool disposed = false;

public MyResourceWrapper()
{
// Constructor for this object.
}

protected override void Dispose(bool disposing)

{
if(!this.disposed)
{
if(disposing)
{
// Release any managed resources here.
}
// Release any unmanaged resources here.
this.disposed = true;
// Call Dispose on your base class.
base.Dispose(disposing);
}
}
}

// This derived class does not have Finalize code

// or a Dispose method because it inherits them from
// the base class.
30 Module 9: Memory and Resource Management

The following summarizes the way this design pattern works. Whenever an
object’s Finalize code or Dispose method is called it is always the object’s base
class’ implementation of these methods that is invoked. In the base class both
the Finalize code and Dispose method call the virtual Dispose method, and
this causes the code in the object’s actual class to be invoked. The virtual
Dispose method cleans up its class specific resources. The bool flag indicates
whether the call originated from Finalize or Dispose code. If finalization is
occurring the virtual Dispose method should not call methods in other objects
as these other objects may have already been finalized. The virtual Dispose
method then calls its parent’s class virtual Dispose method allowing the parent
class’ method to release its class specific resources. This calling of the parent
virtual Dispose methods continues until the base class’ virtual Dispose
method is called. This design pattern allows each class in the object’s class
hierarchy to release its class specific resources.

Guidelines for Working with Explicit Resource

Management
The preceding example of the ResourceWrapper design pattern highlights
some important guidelines that you should follow when working with explicit
resource management.
! Suppress finalization of your instance after Dispose has been called:
void System.GC.SuppressFinalize(Object obj);

! Propagate the Dispose method through containment hierarchies. Dispose

should dispose of all resources that are held by an object and any object that
is contained by that object.
• For example, a TextReader object holds on to a Stream object and an
For Your Information
Students will need to Encoding object, but the clients of the TextReader object are unaware
understand the concept of of the Stream object and the Encoding object. You can assume that
containment hierarchies and both the Stream and the Encoding objects have acquired external
how this relates to the resources. When a client calls Dispose on the TextReader object, the
Dispose method to do the TextReader object should in turn call Dispose on the Stream and the
lab. Illustrate this important Encoding objects, thus causing them to release their external resources.
concept with an example or
two. ! Do not assume that the Dispose method will be called. As a precaution, you
should also release resources in the destructor.
• In finalization code, or code that is called by finalization, for example,
freeState, do not propagate the Dispose or Finalize method calls
through the containment hierarchy of the object because these contained
objects may have been finalized already. For the same reason, you
should generally avoid making calls to other objects from within code
that may execute during finalization.
! Throw an ObjectDisposedException when the methods of your class that
depend upon resources that have been disposed are called.

For Your Information ! Consider not having your object be fully usable after calling Dispose. It is
Students will need to be often difficult to recreate an object that has already been disposed.
able to determine which ! Allow your Dispose method to be called more than once without throwing
methods require resources an exception. It is a no-op after the first call.
that may have been
disposed to be able to do
the lab. Illustrate this
important concept with an
example or two.
Module 9: Memory and Resource Management 31

Using a Domain-Specific Name

Occasionally, a domain-specific name is more appropriate than the Dispose
For Your Information method. For example, a file encapsulation may want to use the name Close. In
Students will need to
implement a domain-specific
this case, you should implement Dispose and have the Close method call it, as
name in the lab. shown in the following design pattern:

Note You can replace Close with a method name appropriate to your domain.

// Do not make this method virtual.

// A derived class should not be allowed
// to override this method.
public void Close()
{
// Call the Dispose method with no parameters.
Dispose();
}
32 Module 9: Memory and Resource Management

Demonstration: The IDisposable Interface

Topic Objective
To demonstrate how to
perform explicit resource
management by using the
IDisposable interface.
Lead-in
This demonstration shows
how to perform explicit
resource management by
using the IDisposable
interface.

*ILLEGAL FOR NON-TRAINER USE**

This demonstration shows how to perform explicit resource management by
using the IDisposable interface.

For Your Information Note The DisposeObj class in the demonstration does not contain any
Use the debugger to step managed resources that have Dispose methods. Therefore, it can use an
through the code while you implementation of the Dispose method that is simpler than the more general
point out features and ask design pattern.
students what they think will
happen next. In this section
run the DisposeDemo // This method demonstrates how to implement a type that
method. // allows its users to explicitly dispose/close the object.
// For many objects this paradigm is strongly encouraged.
private static void DisposeDemo() {
Display(0,
"\n\nDemo start: Disposing an object versus Finalize.", +1);
DisposeObj obj = new DisposeObj("Explicitly disposed");
// Explicitly cleanup this object, Finalize should run
obj.Dispose();
obj = null;
Collect();
// Finalize should NOT run (it was suppressed)
WaitForFinalizers();

obj = new DisposeObj("Implicitly disposed");

obj = null;
Collect();
// No explicit cleanup, Finalize SHOULD run
WaitForFinalizers();
Display(-1,
"Demo stop: Disposing an object versus Finalize.", 0);
}
Module 9: Memory and Resource Management 33

Temporary Resource Usage Design Pattern

Topic Objective ! Temporary Resource Use
To explain how to allocate, # Allocate a resource, use it, and dispose of it
use, and dispose of a
resource in a short period of ! Try and Finally
time.
void
void DoSomething()
DoSomething() {{
Lead-in Resource
In a temporary resource use Resource rr == new
new Resource(...);
Resource(...);
try
try { r.Foo(); }}
{ r.Foo();
scenario, you allocate, use, finally
and dispose of a resource in finally {{
if
if (r
(r !=
!= null)
null) ((IDisposable)r).Dispose();
((IDisposable)r).Dispose();
a short period of time.
}}
}}

! Using Statement
using
using (Resource
(Resource r1
r1 == new
new Resource())
Resource()) {{
r1.Foo();
r1.Foo();
}}
*****************************ILLEGAL FOR NON-TRAINER USE******************************
In a temporary resource use scenario, you allocate, use, and dispose of a
resource in a short period of time. The best way to ensure that the resource is
disposed of, regardless of whether an exception is thrown, is to use a try and
finally block.
In the following example, a method named DoSomething needs to temporarily
use an object of class Resource where Resource implements the IDisposable
interface according to the guidelines that were specified in the preceding topic.
void DoSomething() {
Resource r = new Resource(...); // acquire resource
try {
r.Foo(); // use resource
}
finally { // release resource
if (r != null) ((IDisposable)r).Dispose();
}
}
34 Module 9: Memory and Resource Management

Handling Nested Try and Finally Blocks

The syntax in the preceding example becomes even more awkward when more
than one resource is used, and the try and finally blocks require nesting, as in
the following example:
Resource r1 = new Resource();
try {
Resource r2 = new Resource();
try {
r1.Foo();
r2.Foo();
}
finally {
r2.Dispose();
}
}
finally {
r1.Dispose();
}

C# provides the following using statement to simplify the syntax:

using-statement:
using ( resource-acquisition ) embedded-statement
resource-acquisition:
local-variable-declaration
expression
The using statement requires that the type of the resource acquisition be a type
that implements System.IDisposable. Local variables that are declared in a
resource acquisition are read-only and must include an initializer. In the
following example, Resource is a reference type that implements IDisposable:
using (Resource r1 = new Resource()) {
r1.Foo();
}

This statement is semantically equivalent to the following statement:

Resource r1 = new Resource();
try {
r1.Foo();
}
finally {
if (r1 != null) ((IDisposable)r1).Dispose();
}
Module 9: Memory and Resource Management 35

The following example:

using (Resource r1 = new Resource(),
Resource r2 = new Resource()) {
r1.Foo();
r2.Foo();
}

is semantically equivalent to:

using (Resource r1 = new Resource())
using (Resource r2 = new Resource()) {
r1.Foo();
r2.Foo();
}

By expansion, the preceding example is semantically equivalent to:

Resource r1 = new Resource();
try {
Resource r2 = new Resource();
try {
r1.Foo();
r2.Foo();
}
finally {
if (r2 != null) ((IDisposable)r2).Dispose();
}
}
finally {
if (r1 != null) ((IDisposable)r1).Dispose();
}
36 Module 9: Memory and Resource Management

" Optimizing Garbage Collection

Topic Objective
To provide an overview of
the section topics.
! Weak References
Lead-in
In the .NET Framework, ! Generations
garbage collection has
several advanced features ! Additional Performance Features
that you can use to improve
the performance of your
software.

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework common language runtime garbage collection has several
advanced features that you can use to improve the performance of your
software.
In addition to optimizing garbage collection programmatically, you can use the
Performance Monitor tool (Perfmon.exe) to tune your application and build in
multiprocessor support to enhance performance.
Module 9: Memory and Resource Management 37

Weak References
Topic Objective
To introduce the use of
weak references to
conserve memory ! A Weak Reference Allows an Object to Be Collected If
resources. Memory Is Low
Lead-in Object
Object obj
obj == new
new Object();
Object(); //
// create
create strong
strong reference
reference
A weak reference allows WeakReference wr = new WeakReference(obj);
WeakReference wr = new WeakReference(obj);
garbage collection to collect obj
objects if memory in the obj == null;
null; //
// remove
remove strong
strong reference
reference
//
// ...
...
managed heap is low. obj
obj == (Object)
(Object) wr.Target;
wr.Target;
if
if (obj !=
(obj != null)
null) {//garbage
{//garbage collection
collection hasn’t
hasn’t occurred
occurred
// ...
// ...
}}
else
else {//
{// object
object was
was collected,
collected, reference
reference is
is null
null
//...
//...
}}

*ILLEGAL FOR NON-TRAINER USE**

A weak reference to an object allows garbage collection to collect that object if
memory in the managed heap is low. Weak references are useful in an
application that has large amounts of easily reconstructed data. If the weak
reference’s object has not had its memory resources released by garbage
collection, then the application can avoid the cost of reconstructing the data.

Strong References vs. Weak References

In the common language runtime, the garbage collection process reclaims
inaccessible or unreachable memory that is allocated to an object. An object
becomes unreachable if all references to it become invalid. For example, if an
object’s references are set to a null reference, it is unreachable.
A directly or indirectly referenced object is reachable, and garbage collection is
not permitted to reclaim it. A reference to a reachable object is called a strong
reference.
A weak reference also references a reachable object, or target. You acquire a
strong reference to the target by assigning the value of the target property to a
variable. However, if there are no strong references to the target, the target
becomes eligible for garbage collection, even though it still has a weak
reference.
38 Module 9: Memory and Resource Management

Retrieving the Target

There may be a delay between the time when an object becomes eligible for
garbage collection and the time when it is collected. If you attempt to retrieve
the target after it has been collected, you will only retrieve a null reference. If
the target has not yet been collected, you will retrieve a valid reference.
The following example shows how to use weak references to improve
performance:
Object obj = new Object(); // create strong reference
WeakReference wr = new WeakReference(obj);
obj = null; // remove strong reference
//...

obj = (Object) wr.Target;

if (obj != null) {
// garbage collection has not occurred,
// obj valid reference
// ...
}
else
{
// object was collected, reference is null
//...
}

A WeakReference object can specify whether the reference to its target is

maintained after finalization. In this way, it can specify whether the weak
reference should track the target’s resurrection.
The following table defines two types of weak references.
Type of weak reference Definition

Short weak reference Does not track resurrection

Long weak reference Tracks resurrection
Module 9: Memory and Resource Management 39

Demonstration: Weak References

Topic Objective
To demonstrate how
garbage collection handles
weak references.
Lead-in
This demonstration shows
how garbage collection
handles weak references.

*ILLEGAL FOR NON-TRAINER USE**

This demonstration shows how garbage collection handles weak references.

For Your Information Important Using the debugger to single-step through the WeakRefDemo code
In this section run the may prevent the garbage collection process from collecting an object that is
WeakRefDemo method. only referenced by a weak reference. Instead of using the debugger to single-
Read and follow the step through the code you should set breakpoints at the beginning and end of
procedure in the Note and
the WeakRefDemo method to observe that objects with only weak references
avoid using the debugger to
to them are collected.
single-step through the
WeakRefDemo code.
40 Module 9: Memory and Resource Management

// This method demonstrates how weak references (WR) work. A

// WR allows the GC to collect objects if the managed heap is
// low on memory.
// WRs are useful to apps that have large amounts of easily-
// reconstructed data that they want to keep around to improve
// performance. But, if the system is low on memory,
// the objects can be destroyed and replaced when
// the app knows that it needs it again.
private static void WeakRefDemo(Boolean trackResurrection) {
Display(0, String.Format(
"\n\nDemo start: WeakReferences that {0}track !
resurrections.",
trackResurrection ? "" : "do not "), +1);

// Create an object
BaseObj obj = new BaseObj("WeakRef");

// Create a WeakReference object that refers to the new

// object
WeakReference wr =
new WeakReference(obj, trackResurrection);

// The object is still reachable, so it is not finalized.

Collect();
// The Finalize code should NOT execute
WaitForFinalizers();
obj.Display("Still exists");

// Let's remove the strong reference to the object

obj = null; // Destroy strong reference to this object

// The following line creates a strong reference to the

// object
obj = (BaseObj) wr.Target;
Display("Strong reference to object obtained: " +
(obj != null));

// Destroy strong reference to this object again.

obj = null;

// The GC considers the object to be unreachable and

// collects it.
Collect();
WaitForFinalizers(); // Finalize should run.

// This object resurrects itself when its Finalize code is

// called.
// If wr is NOT tracking resurrection, wr thinks the object
// is dead
// If wr is tracking resurrection, wr thinks the object is
// still alive

(Code continued on the following page.)

Module 9: Memory and Resource Management 41

// NOTE: If the object referred to by wr doesn't have a

// Finalize code,
// then wr would think that the object is dead regardless of
// whether wr is tracking resurrection or not.

// The following line attempts to create a strong reference

// to the object.
obj = (BaseObj) wr.Target;
Display("Strong reference to object obtained: " +
(obj != null));

if (obj != null) {
// The strong reference was obtained so this wr must be
// tracking resurrection. At this point we have a strong
// reference to an object that has been finalized but its
// memory has not yet been reclaimed by the collector.
obj.Display("See, I'm still alive");

// Destroy the strong reference to the object

obj = null;

// Collect reclaims the object's memory since this

// object has no Finalize code registered for it
// anymore.
Collect();
WaitForFinalizers(); // We should see nothing here

obj = (BaseObj) wr.Target; // This now returns null

Display("Strong reference to object obtained: " +
(obj != null));
}
// Cleanup everything about this demo so there is no effect
// on the next demo
// Destroy strong reference (if it exists)
obj = null;
wr = null; // Destroy the WeakReference object (optional)
Collect();
WaitForFinalizers();

// NOTE: You are discouraged from using the

// WeakReference.IsAlive property
// because the object may be killed immediately after
// IsAlive returns making the return value incorrect.
// If the Target property returns a non-null value,
// then the object is alive and will stay alive
// since you have a reference to it. If Target returns null,
// then the object is dead.
Display(-1, String.Format(
"Demo stop: WeakReferences that {0}track resurrections.",
trackResurrection ? "" : "do not "), 0);
}
42 Module 9: Memory and Resource Management

Generations
Topic Objective
To explain how the .NET
Framework common ! To Force Garbage Collection of Generation 0 Through a
language runtime uses a Specified Generation:
system of generations to
make garbage collection void
void System.GC.Collect(int
System.GC.Collect(int Generation);
Generation);
more efficient.
Lead-in ! To Determine the Generation of an Object:
To improve the performance
of garbage collection, the
.NET Framework uses a Int32
Int32 System.GC.GetGeneration(Object
System.GC.GetGeneration(Object obj);
obj);
system based on object
generations.
! To Return the Maximum Number of Generations That
the System Currently Supports:

Int32
Int32 System.GC.MaxGeneration;
System.GC.MaxGeneration;

*ILLEGAL FOR NON-TRAINER USE**

To improve the performance of garbage collection, the .NET Framework uses a
system based on object generations, which works as follows:
1. When a managed object is created by using the new operator and is added to
the managed heap, it becomes part of generation 0.
2. After garbage collection is invoked, any generation 0 objects that remain in
the managed heap are promoted to become members of generation 1.
3. Any generation 1 objects that remain in the managed heap are promoted to
become members of generation 2.
Because generation 2 is the highest generation that is currently supported,
generation 2 objects that remain in the managed heap remain in
generation 2.

When garbage collection is invoked to free heap space, its performance is

improved because it only compacts the section of the managed heap that
contains generation 0 objects.
Typically, the newer an object is, the shorter its lifetime will be. Therefore,
sufficient space is usually freed when generation 0 is compacted. If sufficient
space cannot be obtained when generation 0 is compacted, garbage collection
will compact the older generations.
Module 9: Memory and Resource Management 43

To force the collection of generations from 0 through a specified generation,

you can call the .NET Framework System.GC.Collect method, as follows:
void System.GC.Collect(int Generation);

The System.GC.GetGeneration method returns the current generation of an

object as follows:
Int32 System.GC.GetGeneration(Object obj);

The System.GC.MaxGeneration property returns the maximum number of

generations that the system currently supports. It is written as follows:
Int32 System.GC.MaxGeneration;
44 Module 9: Memory and Resource Management

Demonstration: Generations
Topic Objective
To demonstrate how
garbage collection handles
generations.
Lead-in
This demonstration shows
how garbage collection
handles generations.

*ILLEGAL FOR NON-TRAINER USE**

This demonstration shows how garbage collection handles generations.
// This method demonstrates how objects are promoted between
For Your Information // generations.
Use the debugger to step
// Applications could take advantage of this info to improve
through the code while you
point out features and ask // performance but most applications will ignore this info.
students what they think will private static void GenerationDemo() {
happen next. In this section Display(0, "\n\nDemo start: Understanding Generations.",
run the GenerationDemo +1);
method.
// Let's see how many generations the managed heap supports
// (we know it's 2)
Display("Maximum GC generations: " + GC.MaxGeneration);

// Create a new BaseObj in the heap

GenObj obj = new GenObj("Generation");

// Since this object is newly created, it should be in

// generation 0
obj.DisplayGeneration(); // Displays 0

// Performing a GC promotes the object's generation

Collect();
obj.DisplayGeneration(); // Displays 1

Collect();
obj.DisplayGeneration(); // Displays 2

Collect();
obj.DisplayGeneration(); // Displays 2 (max generation)

(Code continued on the following page.)

Module 9: Memory and Resource Management 45

// Destroy the strong reference to this object

obj = null;

Collect(0); // Collect objects in generation 0

WaitForFinalizers(); // We should see nothing

// Collect objects in generations 0 and 1

Collect(1);
WaitForFinalizers(); // We should see nothing

Collect(2); // Same as Collect()

// Now, we should see the Finalize code run
WaitForFinalizers();

Display(-1, "Demo stop: Understanding Generations.", 0);

}
46 Module 9: Memory and Resource Management

Additional Performance Features

Topic Objective
To introduce additional
resources for improved
application performance. ! Performance Monitoring
Lead-in ! Large Object Heap
In addition to
programmatically ! Multiprocessor Support
manipulating garbage
collection through weak ! Unsafe Code
references and generations,
you can use other features
and techniques to improve
application performance.

*ILLEGAL FOR NON-TRAINER USE**

In addition to programmatically manipulating garbage collection through weak
references and generations, you can use other features and techniques to
improve application performance.

Performance Monitoring
You can obtain real-time information about the memory activity of the .NET
Framework common language runtime by using performance counters.
You can view these counters by using the Performance Monitor tool
(Perfmon.exe). To execute this program, click Start, click Run, and in the text
box, type perfmon.exe.
You can also execute the program by clicking Control Panel, double-clicking
Administrative Tools, and double-clicking Performance.
To view .NET Framework common language runtime memory statistics in the
Performance window:
1. Click the System Monitor icon under the Console Root folder.
2. Click the + button in the right pane to add a counter to the System Monitor.
3. Specify the computer that you wish to monitor.
4. In the Performance object field, select .NET CLR Memory.
5. Select the desired counters and application instance.
You can obtain descriptions of the counters by clicking the Explain button.

In the future, you will also be able to read these counters by using the APIs that
will be provided by the .NET Framework class library.
Module 9: Memory and Resource Management 47

Large Object Heap

Objects that are larger than 20,000 bytes are allocated from a separate special
heap. Garbage collection handles large objects in the same way as it handles
other managed heap objects, except it does not compact the separate special
heap to avoid the additional performance cost of shifting large blocks of
memory.

Multiprocessor Support
The .NET Framework common language runtime provides two forms of
garbage collection: a server version (MSCorSvr.dll) and a workstation version
(MSCorWks.dll). The server version is multithreaded and highly scalable, while
the workstation version is single-threaded and concurrent. Both versions feature
low fragmentation, low overhead, and efficient use of cache space.
The server version of the common language runtime contains features that
improve the efficiency of resource collection. With synchronization-free
allocations and scalable collections, a multiprocessor system receives a
managed heap that is split into as many sections as there are CPUs. Each CPU
has its own thread, which enables the runtime to perform garbage collection on
different heaps simultaneously. If you have a garbage collection bottleneck, you
can improve performance by scaling your application to a multiprocessor
system.

Using Unmanaged Code to Control Garbage Collection

When you need a higher degree of control or that extra margin of performance,
C# provides the ability to write code that can deal directly with pointer types,
and fix objects to temporarily prevent garbage collection from moving them.
You must clearly mark such code in C# with the unsafe modifier. This ensures
that other developers cannot possibly use unsafe features accidentally, and that
the compiler and the common language runtime work together to ensure that
unmanaged code cannot masquerade as safe code.
You should note that unmanaged code is not verifiable by the .NET Framework
common language runtime and should only be executed when trusted. It does,
however, offer developers and users a way to optimize performance.
Further discussion of unmanaged code and memory management is beyond the
scope of this course.
48 Module 9: Memory and Resource Management

Lab 9: Memory and Resource Management

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will learn
how to use classes to create
an application that explicitly
manages resources by
implementing a design
pattern that is based on the
IDisposable interface. You
will also learn how to create
an application that implicitly
manages resources by
using destructors.

*ILLEGAL FOR NON-TRAINER USE**

Objectives
After completing this lab, you will be able to:
! Create an application, with classes, that explicitly manages resources by
implementing a design pattern based on the IDisposable interface.
! Create an application that implicitly manages resources by using
destructors.

Lab Setup
Starter and solution files are associated with this lab. The starter files are in the
folder <install folder>\Labs\Lab09\Starter. The solution files for this lab are in
the folder <install folder>\Labs\Lab09\Solution.

Scenario
In this lab, you are provided with a Microsoft Visual Studio® .NET console
application as a starting point. The application is named Memory and Resource
Management. It allows a user to enter text data. When the user has finished
entering data, the application outputs the number of completed sentences and
the character count, and then the text. The text is formatted so that each
sentence is displayed on a separate line without an ending period.
The application is implemented by using a SentenceFormatter object that
buffers the input text until a completed sentence is detected or until its Close
method is called.
Module 9: Memory and Resource Management 49

When a completed sentence is detected or its Close method is called, the

SentenceFormatter object sends its buffered text to a SimpleTextBuffer
object. The SimpleTextBuffer object buffers this text until it is closed or
finalized. At that time, the SimpleTextBuffer object outputs its buffered text to
the console.
In this lab, the Memory and Resource Management application is used to
illustrate some key points about .NET Framework resource management. To
provide explicit and implicit resource management, you will modify this
program to follow the design pattern that is described in Module 9.

Estimated time to complete this lab: 60 minutes

50 Module 9: Memory and Resource Management

Exercise 1
Programming for Explicit Resource Management
In this exercise, you will modify the Memory and Resource Management
application to incorporate explicit resource management.

! Examine the application

1. In Visual Studio .NET, open the Memory and Resource Management
project, which is located in <install folder>\Labs\Lab09\Starter\
Memory and Resource Management.
2. Open the Memory and Resource Management.cs file and examine the code.
3. Build and run the Memory and Resource Management application.
The following text should appear in the console output:
Enter text, when finished enter an empty line

4. Enter the following text, which is followed by an empty line, as prompted:

hello world.are you out there?

Text similar to the following should appear in the console output:

SimpleTextBuffer:

hello world
are you out there?

Completed Sentences 1, Output Characters 29

hit enter to exit program

Module 9: Memory and Resource Management 51

! Add explicit resource management

Tip For detailed explanations about and code examples for adding explicit
resource management, see The IDisposable Interface and the Dispose method
in this module.

1. Modify the SentenceFormatter and SimpleTextBuffer classes to inherit

from IDisposable.
2. For each of these classes, add a private member of type bool named
disposed to indicate whether the object’s non-memory resources have been
released. Initialize the value of disposed to false.
3. For each of these classes, add a protected virtual void Dispose method that
takes a single bool parameter named disposing. If the object’s disposed flag
indicates that the object has not already been disposed:
a. If the parameter disposing indicates that the object is not in finalization
mode, then propagate the Dispose/Close method call through any
containment hierarchies.

Tip Propagating the Dispose/Close method call through a containment

hierarchy is discussed in the topic The IDisposable Interface and the
Dispose Method in Module 9.

Note The SentenceFormatter should send its text buffer to its contained
SimpleTextBuffer object named aSimpleTextBuffer before it calls that
SimpleTextBuffer object’s Close method.

b. Free the object’s internal state and set disposed to indicate that the
object has been disposed.
Multiple calls to protected virtual void Dispose should not throw an
exception.
4. For both classes, add a public void Dispose method that takes no
arguments. This method calls the protected virtual void Dispose method
created in step 3 with true as its argument followed by a call to the GC
class’s method to suppress finalization.
5. For both classes, modify the Close method to call the public void Dispose
method.
6. For the SentenceFormatter and SimpleTextBuffer methods, which require
resources that are freed by their classes’ protected virtual void Dispose
method, add an initial check that throws an ObjectDisposedException if
those resources have been released.
52 Module 9: Memory and Resource Management

Tip When the SentenceFormatter’s protected virtual void Dispose method

is called, it frees its sentenceBuffer and aSimpleTextBuffer resources. The
SentenceFormatter’s SentenceCount property does not use either of these
resources and therefore does not need to check if these resources have been
released. The ProcessInput method uses both these resources and therefore
must check whether these resources have been released.

Note Explicit resource management will be investigated further in the next

exercise.
Module 9: Memory and Resource Management 53

Exercise 2
Programming for Implicit Resource Management
In this exercise, you will modify the Memory and Resource Management
application to incorporate implicit resource management.

! Add implicit resource management

1. Add destructors to the SentenceFormatter and SimpleTextBuffer classes.
These destructors should free only their object’s internal state by calling the
protected virtual void Dispose method with false. Add code to the
destructors to output to the console the name of the class and the fact that
the destructor was executed.

Note Even though you have inserted code to do implicit resource

management, the program is still explicitly managing its resources through
the following method call in the Main method:
aSentenceFormatter.Close();

2. Build and run the Memory and Resource Management application.

As in the preceding exercise, the following text should appear in the console
output:
Enter text, when finished enter an empty line

3. Enter the following text, and then enter an empty line, as prompted:
hello world.are you out there?

Text similar to the following should appear in the console output:

SimpleTextBuffer:

hello world
are you out there?

Completed Sentences 1, Output Characters 29

hit enter to exit program

Note With explicit resource management, the output is identical to the output
in Exercise 1. All the characters you entered are output and counted.
54 Module 9: Memory and Resource Management

! Test implicit resource management performance

1. In the Main method, add comments to the beginning of the following line of
code so that the Close method will not be invoked:
aSentenceFormatter.Close();

2. In the preceding step there is a statement after the code that outputs the
sentence and character count to the console. After this Console.WriteLine
statement, add code to assign the SimpleTextBuffer and
SentenceFormatter objects to null, invoke garbage collection on all
generations, and wait for pending finalizers.
3. Build and run the Memory and Resource Management application.
As in the preceding exercise, the following text should appear in the console
output:
Enter text, when finished enter an empty line

4. Enter the following text, followed by an empty line, as prompted:

hello world.are you out there?

Text similar to the following should appear in the console output:

Completed Sentences 1, Output Characters 11

SentenceFormatter destructor called

SimpleTextBuffer:

hello world
SimpleTextBuffer destructor called

hit enter to exit program

Note Observe the difference in the number of output characters when using
explicit and implicit resource management. Explicit resource management
outputs all the characters you entered because it propagates the Close/Dispose
method call down the containment hierarchy, thereby flushing all of the buffers.
Implicit resource management cannot safely do this propagation because of the
nondeterministic order of destructor calls. Therefore, not all of the characters
you entered are output.
Module 9: Memory and Resource Management 55

Review
Topic Objective
To reinforce module
objectives by reviewing
key points. ! Memory Management Basics
Lead-in ! Non-Memory Resource Management
The review questions cover
some of the key concepts ! Implicit Resource Management
taught in the module.
! Explicit Resource Management
! Optimizing Garbage Collection

*ILLEGAL FOR NON-TRAINER USE**

1. Describe two common problems with manual memory management that the
.NET Framework’s automatic memory management addresses.
Failure to release memory (Memory leaks)
Accessing invalid memory (dangling pointer references)

2. Describe the .NET Framework mechanism that is used to provide implicit

resource management.
During the finalization phase of garbage collection, garbage collection
calls Finalize code (C# destructor), which allows an object to properly
clean up its resources before its memory resources are freed.

3. State why explicit resource management is desirable. Describe the interface

that a class should inherit from and the method(s) that a class should
implement to provide explicit memory management.
Implicit resource management is non-deterministic, and therefore an
application cannot know exactly when a resource will be freed. Explicit
resource management allows a client to invoke a method to
deterministically free the resource. Therefore, classes should inherit
from IDisposable and implement its Dispose method.
Also garbage collection’s non-deterministic ordering of calls to finalize
code makes it dangerous for classes to refer to other objects during
finalization. Therefore, explicit resource management may be the only
safe way for a class to refer to other objects when it releases resources,
as, for example, when it flushes buffers.
56 Module 9: Memory and Resource Management

4. State the purpose of weak references.

Weak references are useful in applications that have large amounts of
easily reconstructed data that should be maintained to improve
performance. A weak reference allows garbage collection to collect
these objects if memory in the managed heap is low.

5. Explain how and why generations are used by garbage collection.

When garbage collection is invoked to free heap space, its performance
is improved because it only compacts the section of the managed heap
that contains generation 0 objects. Typically, the newer an object is, the
shorter its lifetime will be. Therefore, sufficient space is usually freed
when generation 0 is compacted. If sufficient space cannot be obtained
when generation 0 is compacted, garbage collection will compact the
older generations.

THIS PAGE INTENTIONALLY LEFT BLANK

Module 10: Data
Streams and Files

Contents

Overview 1
Streams 2
Readers and Writers 5
Basic File I/O 8
Lab 10: Files 21
Review 26
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, place or event is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

 2001-2002 Microsoft Corporation. All rights reserved.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Module 10: Data Streams and Files iii

Instructor Notes
Presentation: After completing this module, students will be able to:
45 Minutes
! Use Stream objects to read and write bytes to backing stores, such as
Lab: strings and files.
45 Minutes
! Use BinaryReader and BinaryWriter objects to read and write primitive
types as binary values.
! Use StreamReader and StreamWriter objects to read and write characters
to a stream.
! Use StringReader and StringWriter objects to read and write characters to
strings.
! Use Directory and DirectoryInfo objects to create, move, and enumerate
through directories and subdirectories.
! Use FileSystemWatcher objects to monitor and react to changes in the file
system.
! Explain the key features of the Microsoft® .NET Framework isolated storage
mechanism.

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach
this module.

Required Materials
To teach this module, you need the Microsoft PowerPoint® file 2349B_10.ppt.

Preparation Tasks
To prepare for this module, you should:
! Read all of the materials for this module.
! Complete the lab.
iv Module 10: Data Streams and Files

Module Strategy
Use the following strategy to present this module:
! Streams
Briefly review fundamental stream operations and introduce the stream
classes that are provided by System.IO. Point out that this module discusses
synchronous operations only; asynchronous operations are beyond the scope
of this course.
Tell students that the NetworkStream class is covered in more detail in
Module 11, “Internet Access,” in Course 2349B, Programming with the
Microsoft .NET Framework (Microsoft Visual C#™.NET).
! Readers and Writers
Cover the commonly used reader and writer classes that are used to input
and output to streams and strings that use types other than bytes.
! Basic File I/O
Discuss in more detail the stream classes that are provided by System.IO
for manipulating files and directories.
Discuss the security issues that are associated with writing code that will be
downloaded over the Internet.
Module 10: Data Streams and Files 1

Overview
Topic Objective
To provide an overview of
the module topics and
objectives.
! Streams
Lead-in ! Readers and Writers
In this module, you will learn
about how to use types that ! Basic File I/O
allow reading from and
writing to data streams and
files.

*ILLEGAL FOR NON-TRAINER USE**

The System.IO namespace contains types that allow synchronous and
asynchronous reading from and writing to data streams and files. This module
discusses synchronous operations only, because asynchronous operations are
beyond the scope of this course.
After completing this module, you will be able to:
! Use Stream objects to read and write bytes to backing stores, such as
For Your Information strings and files.
When you talk about a
particular class, you may ! Use BinaryReader and BinaryWriter objects to read and write primitive
want to display the class types as binary values.
information for System.IO
from the .NET Framework ! Use StreamReader and StreamWriter objects to read and write characters
Reference section in the to a stream.
.NET Framework SDK. ! Use StringReader and StringWriter objects to read and write characters to
strings.
! Use Directory and DirectoryInfo objects to create, move, and enumerate
through directories and subdirectories.
! Use FileSystemWatcher objects to monitor and react to changes in the file
system.
! Explain the key features of the Microsoft® .NET Framework isolated
storage mechanism.
2 Module 10: Data Streams and Files

Streams
Topic Objective
To introduce the functions of ! A Way to Read and Write Bytes from and to a Backing Store
the Stream class and its
subclasses. " Stream classes inherit from System.IO.Stream
! Fundamental Stream Operations: Read, Write, and Seek
Lead-in
Streams provide a way to " CanRead, CanWrite, and CanSeek properties
read and write bytes from ! Some Streams Support Buffering for Performance
and to a backing store. A " Flush method outputs and clears internal buffers
backing store is a storage
medium, such as a disk or ! Close Method Frees Resources
memory. " Close method performs an implicit Flush for buffered streams
! Stream Classes Provided by the .NET Framework
" NetworkStream, BufferedStream, MemoryStream, FileStream,
CryptoStream
! Null Stream Instance Has No Backing Store

*ILLEGAL FOR NON-TRAINER USE**

Streams provide a way to read and write bytes from and to a backing store. A
backing store is a storage medium, such as a disk or memory.
All classes that represent streams inherit from the Stream class. The Stream
class and its subclasses provide a generic view of data sources and repositories,
and isolate the programmer from the specific details of the operating system
and underlying devices.

Fundamental Stream Operations

Streams allow you to perform three fundamental operations:
1. You can read from streams.
Reading is the transfer of data from a stream into a data structure, such as an
array of bytes.
2. You can write to streams.
Writing is the transfer of data from a data structure into a stream.
3. Streams can support seeking.
Seeking is the querying and modifying of the current position within a
stream. Seek capability depends on the kind of backing store that a stream
has. For example, network streams have no unified concept of a current
position and therefore typically do not support seeking.

Depending on the underlying data source or repository, streams may support

only some of these capabilities. An application can query a stream for its
capabilities by using the CanRead, CanWrite, and CanSeek properties.
The Read and Write methods read and write byte data. For streams that
support seeking, the Seek and SetLength methods and the Position and Length
properties can be used to query and modify the current position and length of a
stream.
Module 10: Data Streams and Files 3

Support for Buffering

Some stream implementations perform local buffering of the underlying data to
improve performance. For such streams, you can use the Flush method to clear
internal buffers and ensure that all data has been written to the underlying data
source or repository.
Calling the Close method on a stream flushes any buffered data, essentially
calling the Flush method for you. The Close method also releases operating
system resources, such as file handles, network connections, or memory that is
used for any internal buffering.

Stream Classes Provided by the .NET Framework

The .NET Framework contains several stream classes that derive from the
System.IO.Stream class. The System.Net.Sockets namespace contains the
NetworkStream class. NetworkStream provides the underlying stream of data
for network access and will be discussed in more detail in Module 11, “Internet
Access,” in Course 2349B, Programming with the Microsoft .NET Framework
(Microsoft Visual C#™.NET).
The System.IO namespace contains the BufferedStream, MemoryStream,
and FileStream classes, which are derived from the System.IO.Stream class.

BufferedStream Class
The BufferedStream class is used to buffer reads and writes to another stream.
A buffer is a block of bytes in memory that is used to cache data, thereby
reducing the number of calls to the operating system. Buffers thus can be used
to improve read and write performance. Another class cannot inherit from the
BufferedStream class.

MemoryStream Class
The MemoryStream class provides a way to create streams that have memory
as a backing store, instead of a disk or a network connection. The
MemoryStream class creates a stream out of an array of bytes.

FileStream Class
The FileStream class is used for reading from and writing to files. By default,
the FileStream class opens files synchronously, but it provides a constructor to
open files asynchronously.
4 Module 10: Data Streams and Files

CryptoStream Class
The CryptoStream class defines a stream that links data streams to
cryptographic transformations. The common language runtime uses a stream-
oriented design for cryptography. The core of this design is CryptoStream.
Any cryptographic objects that implement CryptoStream can be chained
together with any objects that implement Stream, so the streamed output from
one object can be fed into the input of another object. The intermediate result
(the output from the first object) does not need to be stored separately. For
further details about the CryptoStream class see the .NET Framework SDK.

Null Stream Instance

There are times when an application needs a stream that simply discards its
output and returns no input. You can obtain such a stream that has no backing
store and that will not consume any operating resources from the Stream
class’s public static field named Null.
For example, you may code an application to always write its output to the
FileStream that is specified by the user. When the user does not want an output
file, the application directs its output to the Null stream. When the Write
methods of Stream are invoked on this Null stream, the call simply returns, and
no data is written. When the Read methods are invoked, the Null stream returns
zero without reading data.
Module 10: Data Streams and Files 5

Readers and Writers

Topic Objective
To show how reader and
writer classes are used to ! Classes That Are Derived from System.IO.Stream Take Byte Input
input and output to streams and Output
and strings. ! Readers and Writers Take Other Types of Input and Output and
Read and Write Them to Streams or Strings
Lead-in
As previously mentioned, ! BinaryReader and BinaryWriter Read and Write Primitive Types to
the Stream class is a Stream
designed for byte input and ! TextReader and TextWriter Are Abstract Classes That Implement
output. You can use the Read Character and Write Character Methods
reader and writer classes to ! TextReader and TextWriter Derived Classes Include:
input and output to streams
and strings using other " StreamReader and StreamWriter, which read and write to a stream
types. " StringReader and StringWriter, which read and write to a string
and StringBuilder respectively

*ILLEGAL FOR NON-TRAINER USE**

As discussed in Streams in this module, the Stream class is designed for byte
input and output. You can use the reader and writer classes to input and output
to streams and strings that use other types.
The following table describes some commonly used reader and writer classes.
Class Description

BinaryReader and BinaryWriter These classes read and write primitive types as
binary values in a specific encoding to and from
a stream.
TextReader and TextWriter The implementations of these classes are
designed for character input and output.
StreamReader and StreamWriter These classes are derived from the TextReader
and TextWriter classes, and read and write their
characters to a stream.
StringReader and StringWriter Theses classes also derive from the TextReader
and TextWriter classes, but read their
characters from a string and write their
characters to a StringBuilder class.

A reader or writer is attached to a stream so that the desired types can be read or
written easily.
6 Module 10: Data Streams and Files

The following example shows how to write data of type Integer to and read
from a new, empty file stream that is named Test.data. After creating the data
file in the current directory, the BinaryWriter class is used to write the integers
0 through 10 to Test.data. Then the BinaryReader class reads the file and
displays the file’s content to the console.
using System;
using System.IO;

class MyStream {
private const string FILE_NAME = "Test.data";
public static void Main(String[] args) {
// Create the new, empty data file.
if (File.Exists(FILE_NAME)) {
Console.WriteLine("{0} already exists!", FILE_NAME);
return;
}
FileStream fs = new FileStream(FILE_NAME,
FileMode.CreateNew);
// Create the writer for data.
BinaryWriter w = new BinaryWriter(fs);
// Write data to Test.data.
for (int i = 0; i < 11; i++) {
w.Write( (int) i);
}
w.Close();
fs.Close();
// Create the reader for data.
fs = new FileStream(FILE_NAME, FileMode.Open,
FileAccess.Read);
BinaryReader r = new BinaryReader(fs);
// Read data from Test.data.
for (int i = 0; i < 11; i++) {
Console.WriteLine(r.ReadInt32());
w.Close();
}
}
}
Module 10: Data Streams and Files 7

In the following example, the code defines a string and converts it to an array of
characters, which can then be read as desired by using the appropriate
StringReader.Read method:
using System;
using System.IO;

public class CharsFromStr

{
public static void Main(String[] args) {
// Create a string to read characters from.
String str = "Some number of characters";
// Size the array to hold all the characters of the
// string, so that they are all accessible.
char[] b = new char[24];
// Create a StringReader and attach it to the string.
StringReader sr = new StringReader(str);
// Read 13 characters from the array that holds
// the string, starting from the first array member.
sr.Read(b, 0, 13);
// Display the output.
Console.WriteLine(b);
// Close the StringReader.
sr.Close();
}
}

The preceding example produces the following output:

Some number o

System.Text.Encoding
Internally, the common language runtime represents all characters as Unicode.
However, Unicode can be inefficient when transferring characters over a
network or when persisting in a file. To improve efficiency, the .NET
Framework class library provides several types that are derived from the
System.Text.Encoding abstract base class. These classes know how to encode
and decode Unicode characters to ASCII, UTF-7, UTF-8, Unicode, and other
arbitrary code pages. When you construct a BinaryReader, BinaryWriter,
StreamReader, or StreamWriter, you can choose any of these encodings. The
default encoding is UTF-8.
8 Module 10: Data Streams and Files

# Basic File I/O

Topic Objective
To introduce the classes of
the System.IO namespace,
which are discussed in this ! FileStream Class
section.
! File and FileInfo Class
Lead-in
The .NET Framework’s ! Reading Text Example
System.IO namespace
provides a number of useful ! Writing Text Example
classes for manipulating
! Directory and DirectoryInfo Class
files and directories.
! FileSystemWatcher
! Isolated Storage

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework’s System.IO namespace provides a number of useful
classes for manipulating files and directories.

Important Default security policy for the Internet and intranets does not allow
access to files. Therefore, do not use the regular, nonisolated storage IO classes
if you are writing code that will be downloaded over the Internet. Use Isolated
Storage instead.

Caution When a file or network stream is opened, a security check is

performed only when the stream is constructed. Therefore, be careful when
handing off these streams to less trusted code or application domains.
Module 10: Data Streams and Files 9

FileStream Class
Topic Objective
To define the FileStream
class and the types that are ! The FileStream Class Is Used for Reading from and Writing to Files
used as parameters in some ! FileStream Constructor Parameter Classes
FileStream constructors.
" FileMode – Open, Append, Create
Lead-in
" FileAccess – Read, ReadWrite, Write
The FileStream class is
used for reading from and " FileShare – None, Read, ReadWrite, Write
writing to files. The FileStream
FileMode, FileAccess, and FileStream ff == new
new FileStream(name,
FileStream(name, FileMode.Open,
FileMode.Open,
FileAccess.Read,
FileAccess.Read, FileShare.Read);
FileShare.Read);
FileShare types are used as
parameters in some ! Random Access to Files by Using the Seek Method
FileStream constructors.
" Specified by byte offset
" Offset is relative to seek reference point: Begin, Current, End

*ILLEGAL FOR NON-TRAINER USE**

The FileStream class is used for reading from and writing to files. The
FileMode, FileAccess, and FileShare types are used as parameters in some
FileStream constructors.

FileMode Parameter
FileMode parameters control whether a file is overwritten, created, or opened,
or any combination of those operations. The following table describes constants
that are used with the FileMode parameter class.
Constant Description

Open This constant is used to open an existing file.

Append This constant is used to append to a file.
Create This constant is used to create a file if it does not exist.

FileAccess Enumeration
The FileAccess enumeration defines constants for read, write, or read/write
access to a file. This enumeration has a FlagsAttribute that allows a bitwise
combination of its member values. A FileAccess parameter is specified in many
of the constructors for File, FileInfo, and FileStream, and in other class
constructors where it is important to control the kind of access that users have
to a file.
10 Module 10: Data Streams and Files

FileShare Enumeration
The FileShare enumeration contains constants for controlling the kind of
access that other FileStreams can have to the same file. This enumeration has a
FlagsAttribute that allows a bitwise combination of its member values.
The FileShare enumeration is typically used to define whether two processes
can simultaneously read from the same file. For example, if a file is opened and
FileShare.Read is specified, other users can open the file for reading but not
for writing. FileShare.Write specifies that other users can simultaneously write
to the same file. FileShare.None declines sharing of the file.
In the following example, a FileStream constructor opens an existing file for
read access and allows other users to read the file simultaneously:
FileStream f = new FileStream(name, FileMode.Open,
FileAccess.Read, FileShare.Read);

Using the Seek Method for Random Access to Files

FileStream objects support random access to files by using the Seek method.
The Seek method allows the read/write position within the file stream to be
moved to any position within the file. The read/write position can be moved by
using byte offset reference point parameters.
The byte offset is relative to the seek reference point, as represented by the
three properties of the SeekOrigin class, which are described in the following
table.
Property Name Description

Begin The seek reference position of the beginning of a stream.

Current The seek reference position of the current position within a stream.
End The seek reference position of the end of a stream.
Module 10: Data Streams and Files 11

File and FileInfo Class

Topic Objective
To introduce the File and ! File Is a Utility Class with Static Methods Used to:
FileInfo classes and
demonstrate how they are " Create, copy, delete, move, and open files
used to create a new object.
! FileInfo Is a Utility Class with Instance Methods Used to:
Lead-in
The File and FileInfo " Create, copy, delete, move, and open files
classes are utility classes
with methods that are " Can eliminate some security checks when reusing
primarily used for the an object.
creation, copying, deletion,
moving, and opening of
! Example:
files. " Assign to aStream a newly created file named foo.txt in
the current directory

FileStream
FileStream aStream
aStream == File.Create("foo.txt");
File.Create("foo.txt");

*ILLEGAL FOR NON-TRAINER USE**

The File and FileInfo classes are utility classes with methods that are primarily
used for the creation, copying, deletion, moving, and opening of files.
All methods of the File class are static and can therefore be called without
having an instance of a file. The FileInfo class contains all instance methods.
The static methods of the File class perform security checks on all methods. If
you are going to reuse an object several times, consider using the corresponding
instance method of FileInfo instead, because the security check will not always
be necessary.
For example, to create a file named Foo.txt and return a FileStream object, use
the following code:
FileStream aStream = File.Create("Foo.txt");

To create a file named Foo.txt and return a StreamWriter object, use the
following code:
StreamWriter sw = File.CreateText("Foo.txt");

To open a file named Foo.txt and return a StreamReader object, use the
following code:
StreamReader sr = File.OpenText("Foo.txt");
12 Module 10: Data Streams and Files

Reading Text Example

Topic Objective
To provide an example of
reading.
! Read Text from a File and Output It to the Console
Lead-in
In the following example,
you read an entire file and //...
//...
are notified when the end of StreamReader
StreamReader srsr == File.OpenText(FILE_NAME);
File.OpenText(FILE_NAME);
the file is detected. String
String input;
input;
while
while ((input=sr.ReadLine())!=null)
((input=sr.ReadLine())!=null) {{
Console.WriteLine(input);
Console.WriteLine(input);
}}
Console.WriteLine
Console.WriteLine ((
"The
"The end
end of
of the
the stream
stream has
has been
been reached.");
reached.");
sr.Close();
sr.Close();
//...
//...

*ILLEGAL FOR NON-TRAINER USE**

In the following example of reading text, you read an entire file and are notified
when the end of the file is detected.
using System;
using System.IO;
public class TextFromFile {
private const string FILE_NAME = "MyFile.txt";
public static void Main(String[] args) {
if (!File.Exists(FILE_NAME)) {
Console.WriteLine("{0} does not exist!", FILE_NAME);
return;
}
StreamReader sr = File.OpenText(FILE_NAME);
String input;
while ((input=sr.ReadLine())!=null) {
Console.WriteLine(input);
}
Console.WriteLine (
"The end of the stream has been reached.");
sr.Close();
}
}

This code creates a StreamReader object that points to a file named MyFile.txt
through a call to File.OpenText. StreamReader.ReadLine returns each line as
a string. When there are no more characters to read, a message is displayed to
that effect, and the stream is closed.
Module 10: Data Streams and Files 13

Writing Text Example

Topic Objective
To provide an example of
writing text.
! Create a File
Lead-in
This example creates a new ! Write a String, an Integer, and a Floating Point Number
text file that is named
MyFile.txt, writes a string, ! Close the File
integer, and floating point
number to it, and finally //...
//...
closes the file. StreamWriter
StreamWriter swsw == File.CreateText("MyFile.txt");
File.CreateText("MyFile.txt");
sw.WriteLine
sw.WriteLine ("This is
("This is my
my file");
file");
sw.WriteLine
sw.WriteLine ((
"I
"I can
can write
write ints
ints {0}
{0} or
or floats
floats {1}",
{1}", 1,
1, 4.2);
4.2);
sw.Close();
sw.Close();
//...
//...

*ILLEGAL FOR NON-TRAINER USE**

The following example creates a new text file that is named MyFile.txt, writes a
string, integer, and floating-point number to it, and finally closes the file.
using System;
using System.IO;

public class TextToFile {

private const string FILE_NAME = "MyFile.txt";
public static void Main(String[] args) {
if (File.Exists(FILE_NAME)) {
Console.WriteLine("{0} already exists!", FILE_NAME);
return;
}
StreamWriter sw = File.CreateText(FILE_NAME);
sw.WriteLine ("This is my file.");
sw.WriteLine (
"I can write ints {0} or floats {1}, and so on.",
1, 4.2);
sw.Close();
}
}
14 Module 10: Data Streams and Files

Directory and DirectoryInfo Class

Topic Objective ! Directory Has Static Methods Used to:
To explain how the " Create, move, and enumerate through directories
Directory and and subdirectories
DirectoryInfo classes are
used to create directory ! DirectoryInfo Has Instance Methods Used to:
listings. " Create, move, and enumerate through directories
and subdirectories
Lead-in
The Directory and " Can eliminate some security checks when reusing an object
DirectoryInfo classes ! Example:
expose routines for creating,
moving, and enumerating " Enumerating through the current directory
through directories and
subdirectories. DirectoryInfo
DirectoryInfo dir
dir == new
new DirectoryInfo(".");
DirectoryInfo(".");
foreach
foreach (FileInfo
(FileInfo ff in
in dir.GetFiles("*.cs"))
dir.GetFiles("*.cs")) {{
String
String name
name == f.FullName;
f.FullName; }}
! Use Path Class Objects to Process Directory Strings

*ILLEGAL FOR NON-TRAINER USE**

The Directory and DirectoryInfo classes expose routines for creating, moving,
and enumerating through directories and subdirectories. All methods of the
Directory class are static and can therefore be called without having an
instance of a directory. The DirectoryInfo class contains all instance methods.
The static methods of the Directory class do a security check on all methods. If
you are going to reuse an object several times, consider using the corresponding
instance method of DirectoryInfo instead, because the security check will then
not always be necessary.
The following example shows how to use the DirectoryInfo class to create a
listing of a directory:
using System;
using System.IO;

class DirectoryLister
{
public static void Main(String[] args)
{
DirectoryInfo dir = new DirectoryInfo(".");
foreach (FileInfo f in dir.GetFiles("*.cs"))
{
String name = f.FullName;
long size = f.Length;
DateTime creationTime = f.CreationTime;
Console.WriteLine("{0,-12:N0} {1,-20:g} {2}", size,
creationTime, name);
}
}
}
Module 10: Data Streams and Files 15

In the preceding example, the DirectoryInfo object is the current directory,

denoted by ("."). The code lists the names of all of the files in the current
directory that have a .cs extension, together with their file size and creation
time.
Assuming that there are .cs files in the \Bin subdirectory of drive C, the output
of this code appears as follows:
953 7/20/2000 10:42 AM C:\Bin\paramatt.cs
664 7/27/2000 3:11 PM C:\Bin\tst.cs
403 8/8/2000 10:25 AM C:\Bin\dirlist.cs

If you want a list of files in another directory, such as C:\, remember to use the
backslash (\) escape character, as in the following example:
"C:\\"

Or, use an @-quoted string literal in C#, as in the following example:

@"C:\"

Paths
To processes directory strings in a cross-platform manner, use the Path class.
The members of the Path class enable you to quickly and easily perform
common operations, such as determining whether a file extension is part of a
path, and combining two strings into one path name.
16 Module 10: Data Streams and Files

FileSystemWatcher
Topic Objective ! FileSystemWatcher Is Used to Monitor a File System
To explain how the ! Creating a FileSystemWatcher Object
FileSystemWatcher
component can be used to FileSystemWatcher
FileSystemWatcher watcher
watcher == new
new FileSystemWatcher();
FileSystemWatcher();
monitor and react to ! Configure
changes in a file system.
watcher.Path
watcher.Path == args[0];
args[0];
Lead-in watcher.Filter
watcher.Filter == "*.txt";
"*.txt";
You use the watcher.NotifyFilter
watcher.NotifyFilter == NotifyFilters.FileName;
NotifyFilters.FileName;
FileSystemWatcher watcher.Renamed
watcher.Renamed +=+= new
new
component to monitor a file RenamedEventHandler(OnRenamed);
RenamedEventHandler(OnRenamed);
system and react when ! Begin Watching
changes to it occur.
watcher.EnableRaisingEvents
watcher.EnableRaisingEvents == true;
true;
! Catch Events
public
public static
static void
void OnRenamed(object
OnRenamed(object s,
s, RenamedEventArgs
RenamedEventArgs e)
e) {{
Console.WriteLine("File:
Console.WriteLine("File: {0}{0} renamed
renamed to
to {1}",
{1}",
e.OldFullPath,
e.OldFullPath, e.FullPath);
e.FullPath); }}

*ILLEGAL FOR NON-TRAINER USE**

You use the FileSystemWatcher component to monitor a file system and react
when changes to it occur. By using the FileSystemWatcher component, you
can quickly and easily launch business processes when specified files or
directories are created, modified, or deleted.
For example, if a group of users is collaborating on a document that is stored in
a shared directory on a server, you can use the FileSystemWatcher component
to easily program your application to watch for changes to the shared directory.
When a change is detected, the component can run processing that notifies each
user through e-mail.
You can configure the component to watch an entire directory and its contents
or a specific file or set of files within a specific directory. To watch for changes
in all files, set the Filter property to an empty string (""). To watch a specific
file, set the Filter property to the file name. For example, to watch for changes
in the file MyDoc.txt, set the Filter property to "MyDoc.txt". You can also
watch for changes in a certain type of file. For example, to watch for changes in
text files, set the Filter property to "*.txt".

Note Hidden files are not ignored.

There are several types of changes you can watch for in a directory or file. For
example, you can watch for changes in Attributes, the LastWrite date and
time, or the Size of files or directories. This is done by setting the
FileSystemWatcher.NotifyFilter property to one of the NotifyFilters values.
For more information on the type of changes you can watch, see NotifyFilters
in the .NET Framework Software Development Kit (SDK).
You can watch for renaming, deletion, or creation of files or directories. For
example, to watch for renaming of text files, set the Filter property to "*.txt"
and call one of the WaitForChanged methods with the WatcherChangeTypes
value Renamed provided.
Module 10: Data Streams and Files 17

Creating a FileSystemWatcher Component

The following example creates a FileSystemWatcher component to watch the
directory that is specified at run time. The component is set to watch for
changes in LastWrite and LastAccess times, and the creation, deletion, or
renaming of text files in the directory. If a file is changed, created, or deleted,
the path to the file prints to the console. When a file is renamed, the old and
new paths print to the console.
using System;
using System.IO;

public class Watcher

{

public static void Main(string[] args)

{
// If a directory is not specified, exit program.
if(args.Length != 1)
{
// Display the proper way to call the program.
Console.WriteLine(
"Usage: Watcher.exe (directory)");
return;
}

// Create a new FileSystemWatcher

// and set its properties.
FileSystemWatcher watcher = new FileSystemWatcher();
watcher.Path = args[0];
/* Watch for changes in LastAccess and LastWrite
times, and the renaming of files or directories */
watcher.NotifyFilter =
NotifyFilters.LastAccess |
NotifyFilters.LastWrite |
NotifyFilters.FileName |
NotifyFilters.DirectoryName;
// Only watch text files.
watcher.Filter = "*.txt";

// Add event handlers.

// The Changed event occurs when changes are made to

// the size, system attributes, last write time, last
// access time, or security permissions in a file or
// directory in the specified Path of a
// FileSystemWatcher.
watcher.Changed += new
FileSystemEventHandler(OnChanged);

(Code continued on the following page.)

18 Module 10: Data Streams and Files

// The Created event occurs when a file or directory

// in the specified Path of a FileSystemWatcher is
// created.
watcher.Created += new
FileSystemEventHandler(OnChanged);

// The Deleted event occurs when a file or directory

// in the specified Path of a FileSystemWatcher is
// deleted.
watcher.Deleted += new
FileSystemEventHandler(OnChanged);

// The Deleted event occurs when a file or directory

// in the specified Path of a FileSystemWatcher is
// deleted.

watcher.Renamed += new
RenamedEventHandler(OnRenamed);

// Begin watching.
watcher.EnableRaisingEvents = true;

// Wait for the user to quit the program.

Console.WriteLine("Press \'q\' to quit the sample.");
while(Console.Read()!='q');
}
// Define the event handlers.
public static void OnChanged(
object source, FileSystemEventArgs e)
{
// Specify what is done when a file is changed,
// created, or deleted.
Console.WriteLine("File: " + e.FullPath + " " +
e.ChangeType);
}

public static void OnRenamed(

object source, RenamedEventArgs e)
{
// Specify what is done when a file is renamed.
Console.WriteLine("File: {0} renamed to {1}",
e.OldFullPath, e.FullPath);
}
}
Module 10: Data Streams and Files 19

Isolated Storage
Topic Objective
To introduce isolated
storage and its potential
uses. ! Isolated Storage Provides Standardized Ways of
Associating Applications with Saved Data
Lead-in
For some applications, such ! Semi-Trusted Web Applications Require:
as downloaded Web
applications and code that " Isolation of their data from other applications' data
may come from untrusted
sources, the basic file " Safe access to a computer’s file system
system does not provide the
necessary isolation and ! System.IO.IsolatedStorage Namespace Contains:
safety.
public
public sealed
sealed class
class IsolatedStorageFile
IsolatedStorageFile :: IsolatedStorage,
IsolatedStorage, IDisposable
IDisposable

public
public class
class IsolatedStorageFileStream
IsolatedStorageFileStream :: FileStream
FileStream

*ILLEGAL FOR NON-TRAINER USE**

Basic file I/O functionality, found in the System.IO root, provides the ability to
access, store, and manipulate data that is stored in hierarchical file systems
whose files are referenced by using unique paths. For some applications, such
as downloaded Web applications and code that may come from un-trusted
sources, the basic file system does not provide the necessary isolation and
safety. Isolated storage is a data storage mechanism that provides isolation and
safety by defining standardized ways of associating code with saved data.

Isolation
When an application stores data in a file, the file name and storage location
must be carefully chosen to minimize the possibility that the storage location
will be known to another application and, therefore, vulnerable to corruption.
Isolated storage provides the means to manage downloaded Web application
files to minimize storage conflicts.

Security Risks of Semi-Trusted Code

It is important to restrict semi-trusted code’s access from a computer's file
system. Allowing code that has been downloaded and run from the Internet to
have access to I/O functions leaves a system vulnerable to viruses and
unintentional damage.
The security risks associated with file access are sometimes addressed by using
access control lists (ACLs), which restrict the access that users have to files.
However, this approach is often not feasible with Web applications because it
requires administrators to configure ACLs on all of the systems on which the
application will run.
20 Module 10: Data Streams and Files

Safety Through Isolated Storage

Administrators can use tools that are designed to manipulate isolated storage to
configure file storage space, set security policies, and delete unused data. With
isolated storage, code no longer needs to invent unique paths to specify safe
locations in the file system, while data is protected from unauthorized access.
There is no need for hard coding of information that indicates where an
application’s storage area is located. With isolated storage, partially trusted
applications can store data in a manner that is controlled by the computer’s
security policy. Security policies rarely grant permission to access the file
system by using standard I/O mechanisms. However, by default, code that runs
from a local computer, a local network, or the Internet is granted the right to use
isolated storage. Web applications can also use isolated storage with roaming
user profiles, thereby allowing a user’s isolated stores to roam with their profile.
The namespace System.IO.IsolatedStorage contains the IsolatedStorageFile
and IsolatedStorageFileStream classes, which applications can use to access
the files and directory in their isolated storage area.
Further discussion of isolated storage is beyond the scope of this course.
Module 10: Data Streams and Files 21

Lab 10: Files

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will create an
application that reads and
writes characters to and
from files, and create an
application that can use
StringReader and
StreamReader objects to
read character data from
either files or strings.

*ILLEGAL FOR NON-TRAINER USE**

Objectives
After completing this lab, you will be able to:
! Create an application that reads and writes characters to and from files.
! Create an application that can use StringReader and StreamReader
objects to read character data from files or strings.

Lab Setup
Starter and solution files are associated with this lab. The starter files are in the
folder <install folder>\Labs\Lab10\Starter, and the solution files are in the
folder <install folder>\Labs\Lab10\Solution.

Scenario
In this lab, you are provided with a Microsoft Visual Studio® .NET console
application as a starting point. The application, named Files, opens one or more
files, which are specified on the command line, and counts each file’s bytes,
characters, words, and lines. The results from each file and the total of all files
are displayed on the console.
The application supports an –f switch to allow the output display to be
redirected to a file and a –t switch to run a special test mode of operation where
input is obtained from a coded-in test string, instead of from user-specified
files. The application is based on a slightly modified version of the .NET
Framework SDK sample, Word Count.

Estimated time to complete this lab: 45 minutes

22 Module 10: Data Streams and Files

Exercise 1
Reading and Writing Files and Strings
In this exercise, you will modify the Files application to output to a specified
file.

! Examine the application

1. In Visual Studio .NET, open the Files project, which is located in
<install folder>\Labs\Lab10\Starter\Files.
2. Open the WordCount.cs file and examine the code. Pay attention to those
methods that you will be modifying: The Main method of the Application
class and the CountStats method of the WordCounter class.
3. Build the WordCount application.
4. Set the application’s command line arguments by performing the following
steps:
a. If the Solution Explorer pane in the Visual Studio .NET window is not
visible, on the View menu, click Solution Explorer.
b. In the Solution Explorer pane, right-click Files to display the context-
sensitive menu, and then click Properties.
c. In the Files Property Pages dialog box, click the Configuration
Properties folder, and then click Debugging.
d. In the right pane under Start Options, set the command line arguments,
as follows:
-a -o -t -foutput.txt test.txt

5. View the WordCount.cs file, and locate the last line in Application’s Main
method, which is:
return 0;

6. Right-click this line, and select Run To Cursor. You should see the
following output:
Replace this Console.WriteLine in Application's Main!
method with code as per the lab
Lines Words Chars Bytes Pathname
Replace this Console.WriteLine in WordCounter's!
CountStats method
0 0 0 0 Test String
----- ----- ----- ----- ---------------------
0 0 0 0 Total in all files
Word usage sorted alphabetically (0 unique words)
Word usage sorted by occurrence (0 unique words)

7. Stop debugging, and in the Main method code of the Application class,
locate the following line of code:
if (ap.OutputFile != null) {

If ap.OutputFile does not contain null, then it contains the name of the
output file that is specified in the –f command line switch.
Module 10: Data Streams and Files 23

8. Replace the following line’s Console.WriteLine call with code that:

a. Assigns fsOut to a FileStream object that creates a file with the
specified name with Write access and no file sharing.
b. Assigns sw to a StreamWriter object that is bound to the FileStream
object created in step a.
c. Redirects the console’s output to the file by associating the
StreamWriter object with the console by using the following
command:
Console.SetOut(sw);

9. Rebuild and run the application, and examine the output file that is specified
in the command line switch options.
The file should be located in the bin\Debug subdirectory. It should contain
the following text:
Lines Words Chars Bytes Pathname
Replace this Console.WriteLine in WordCounter's!
CountStats method
0 0 0 0 Test String
----- ----- ----- ----- ---------------------
0 0 0 0 Total in all files
Word usage sorted alphabetically (0 unique words)
Word usage sorted by occurrence (0 unique words)

! Add the test mode and normal mode CountStats processing

1. Locate the following lines in the CountStats method code of the
WordCounter class:
Boolean Ok = true;
numLines = numWords = numChars = numBytes = 0;
try {

If the –t option has been set, the CountStats caller will have set the
pathname parameter to the empty string, which is called String.Empty.
2. Replace the following line’s Console.WriteLine call with code that:
a. Declares a variable of type TextReader and names it tr.
You use the type TextReader because it is the common base type for
both StringReader and StreamReader. Polymorphism will allow code
that uses a TextReader object to be provided with either a
StringReader or StreamReader object.
b. If the pathname is empty:
i. Create a StringReader that is named sr, which is bound to a
member of WordCounter that is named testString.
ii. Assign the number of bytes in this string to numBytes.
iii. Assign sr to tr.
This assignment does an implicit cast of a StringReader to a
TextReader.
24 Module 10: Data Streams and Files

c. If the pathname is not empty:

i. Create a FileStream that is named fsIn by opening the file that is
specified in the parameter pathname with read access and shared read
access.
ii. Assign the number of bytes in fsIn to numBytes.
iii. Create a StreamReader that is named sr that is bound to this file.
iv. Assign sr to tr.
This assignment does an implicit cast of a StreamReader to a
TextReader
d. In this module, uncomment out the for loop that follows the comment:
// Process every line in the file

e. Following the for loop, add code to close the TextReader object.
3. Rebuild and run the application, and examine the output file in the
bin\Debug subdirectory. It should contain the following text:
Lines Words Chars Bytes Pathname
2 3 16 17 Test String
----- ----- ----- ----- ---------------------
2 3 16 17 Total in all files
Word usage sorted alphabetically (2 unique words)
2: "hello"
1: "world"
Word usage sorted by occurrence (2 unique words)
1: world
2: hello

4. Change the command line options that Visual Studio .NET will use to run
the application to remove the test switch. It should be set to:
-a -o -foutput.txt test.txt
Module 10: Data Streams and Files 25

5. Run the application, and examine the output file in the bin\Debug
subdirectory. It should contain the following text:
Lines Words Chars Bytes Pathname
5 16 65 73 ...\test.txt
----- ----- ----- ----- ---------------------
5 16 65 73 Total in all files
Word usage sorted alphabetically (14 unique words)
1: "aid"
1: "all"
1: "come"
1: "country"
1: "for"
1: "good"
1: "is"
1: "men"
1: "now"
1: "of"
2: "the"
1: "their"
1: "time"
2: "to"
Word usage sorted by occurrence (14 unique words)
1: aid
1: all
1: come
1: country
1: for
1: good
1: is
1: men
1: now
1: of
1: their
1: time
2: the
2: to

6. Examine the file Test.txt in the bin\Debug subdirectory, and verify that the
output is what you expected.
26 Module 10: Data Streams and Files

Review
Topic Objective
To reinforce module
objectives by reviewing
key points. ! Streams
Lead-in ! Readers and Writers
The review questions cover
some of the key concepts ! Basic File I/O
taught in the module.

*ILLEGAL FOR NON-TRAINER USE**

1. Name at least three types of .NET Framework streams and how they differ.
FileStream does reads and writes to a file.
MemoryStream does reads and writes to memory.
BufferedStream is used to buffer reads and writes to another stream.
NetworkStream provides the underlying stream of data for network
access.

2. Name the three basic stream operations.

Read, Write, and Seek.

3. Name the classes that are used to read and write primitive types as binary
values.
BinaryReader and BinaryWriter.

4. Name the method used to provide random access to files.

Seek.
Module 10: Data Streams and Files 27

5. Name the class that you would use to monitor changes to a file system.
FileSystemWatcher.

6. Name the two important features that the .NET Framework’s isolated
storage provides for an application.
Isolation and Safety.
THIS PAGE INTENTIONALLY LEFT BLANK
Module 11:
Internet Access

Contents

Overview 1
Internet Application Scenarios 2
The WebRequest and WebResponse Model 3
Application Protocols 16
Handling Errors 25
Security 28
Best Practices 35
Lab 11: Creating a DateTime Client/Server
Application 36
Review 41
Course Evaluation 43
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, place or event is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

 2001-2002 Microsoft Corporation. All rights reserved.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Module 11: Internet Access iii

Instructor Notes
Presentation: After completing this module, students will be able to:
60 Minutes
! Use the basic request/response model to send and receive data over the
Lab: Internet.
45 Minutes
! Use the System.Net classes to communicate with other applications by
using the HTTP, Transmission Control Protocol (TCP), User Datagram
Protocol (UDP), and Socket Internet protocols.

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach
this module.

Required Materials
To teach this module, you need the Microsoft® PowerPoint® file 2349B_11.ppt.

Preparation Tasks
To prepare for this module, you should:
! Read all of the materials for this module.
! Complete the lab.
iv Module 11: Internet Access

Module Strategy
Use the following strategy to present this module:
! Internet Application Scenarios
Briefly introduce examples of Internet applications that use the System.Net
classes, including server-side ASP.NET applications, peer-to-peer Microsoft
Windows® Forms applications that act as servers and clients to send and
receive data, and client applications that periodically access the network for
updates.
! The WebRequest and WebResponse Model
Introduce the WebRequest and WebResponse model. Explain how the
Microsoft .NET Framework uses the Uniform Resource Identifier (URI) to
identify the desired communication protocol and Internet resource. Discuss
network streams as the means of obtaining and receiving Web data.
Explain how to use the WebRequest class to request data from a server,
invoke the request for the Internet resource, and send data through a
network stream. Discuss how the WebResponse.GetResponseStream
method serves as the means of obtaining a stream that contains response
data from a network resource.
! Application Protocols
Discuss the HTTP, TCP, and UDP protocol support that is provided in the
.NET Framework, as well as information about using the Windows Sockets
interface to implement custom protocols.
! Handling Errors
Discuss how the WebRequest and WebResponse classes can throw system
exceptions, such as InvalidArgumentException, and Web-specific
exceptions, which are instances of WebException and thrown by the
GetResponse method.
! Security
Explain how an application can provide security for sending and receiving
data over the Internet by using a Web proxy, Secure Sockets Layer (SSL)
encryption, Internet authentication, and the NET Framework code access
permissions.
! Best Practices
Briefly outline the list of recommendations that will help students use the
classes that are contained in System.Net more effectively.
Module 11: Internet Access 1

Overview
Topic Objective
To provide an overview of
the module topics and
objectives.
! Internet Application Scenarios
Lead-in ! The WebRequest and WebResponse Model
In this module, you will learn
about the basic ! Application Protocols
request/response model that
is used to send and receive ! Handling Errors
data over the Internet, the
! Security
System.Net classes that
are used to communicate ! Best Practices
with other applications, and
various techniques to
enhance application security
and performance.

*ILLEGAL FOR NON-TRAINER USE**

The Microsoft® .NET Framework System.Net and System.Net.Sockets
namespaces provide a layered, extensible, and managed implementation of
Internet protocols that applications can use to send or receive data over the
Internet. The System.Net classes provide functionality that is similar to the
Microsoft WinInet API. These classes provide varying levels of detail, from a
generic request/response model to control over application protocols and
sockets. In particular, the System.Net classes are designed for writing
scaleable, high-performance applications.
An application can use the System.Net classes to communicate with any other
application that supports the basic Internet protocols. However, that other
application need not be a .NET application. The .NET Framework provides
alternative mechanisms for inter-application communication.
For example, .NET Framework remoting implements a generic mechanism for
.NET Framework objects to interact with one another across application
domains. In addition, the System.Web.Services namespace contains classes for
applications to build and use XML Web services that are based on the standard
Simple Object Access Protocol (SOAP).
For more information about the remoting and XML Web services approaches to
inter-application communication, see Module 12, “Serialization,” in Course
2349B, Programming with the Microsoft .NET Framework (Microsoft
Visual C#™ .NET).
After completing this module, you will be able to:
! Use the basic request/response model to send and receive data over the
Internet.
! Use the System.Net classes to communicate with other applications by
using the Hypertext Transfer Protocol (HTTP), Transmission Control
Protocol (TCP), User Datagram Protocol (UDP), and Socket Internet
protocols.
2 Module 11: Internet Access

Internet Application Scenarios

Topic Objective
To introduce Internet ! Server-Side ASP.NET Applications
application scenarios that
use the System.Net " Obtain data from back-end sources for a browser
classes. request
Lead-in ! Peer-to-Peer Applications
Several types of
applications use the " Send and receive data by acting as servers and clients
System.Net classes to send
or receive data over the
! Client Applications That Periodically Access the
Network
Internet.
" A robust implementation of HTTP 1.1, including:
Pipelining, chunking, authentication, pre-authentication,
encryption, proxy support, server certificate validation,
and connection management

*ILLEGAL FOR NON-TRAINER USE**

Several types of applications use the System.Net classes to send or receive data
over the Internet. The following three Internet application scenarios are
examples of Internet applications that use the System.Net classes:
! Server-side ASP.NET applications that request data from server resources in
response to a browser request.
The System.Net classes are designed for writing scalable, high-performance
ASP.NET middle-tier applications. The server-side ASP.NET scenario
requires a robust middle-tier networking stack that can tolerate a high load.
The System.Net classes specifically fulfill this important customer
requirement. Such features as connection management, pipelining,
Keep-alive, and asynchronous operations ensure strong support for the
middle tier.
In addition, because the System.Net classes are part of an overall
framework, integration with ASP.NET features, such as impersonation and
caching, is seamless.
! Peer-to-peer Windows Forms applications that act as servers and clients to
send and receive data.
! Client applications that periodically access the network for updates.
The System.Net classes expose a robust implementation of the HTTP
protocol. Because a large share of Internet traffic travels over the HTTP
protocol, the protocol’s importance as an application protocol is significant.
The System.Net classes support most of the HTTP 1.1 protocol features.
The advanced features of HTTP 1.1 include pipelining, chunking,
authentication, pre-authentication, encryption, proxy support, server
certificate validation, connection management, and HTTP extensions.
Module 11: Internet Access 3

# The WebRequest and WebResponse Model

Topic Objective
To introduce the topics in
the section.
! Uniform Resource Identifier
Lead-in
Internet applications can be ! NetworkStream Class
classed broadly into two
types: client applications ! Creating a WebRequest
that request information,
and server applications that ! Invoking a WebRequest
respond to information
! Sending Data
requests from clients.
! Receiving Data
! Using the WebRequest and WebResponse Model

*ILLEGAL FOR NON-TRAINER USE**

Internet applications can be classed broadly into two types: client applications
that request information, and server applications that respond to information
requests from clients. The classic Internet client/server application is the World
Wide Web, where people use browsers to access documents and other data that
is stored on Web servers worldwide.
Applications are not limited to playing either the client or server role; the
familiar middle-tier application server responds to requests from clients by
requesting data from another server. In this case, it is acting as both a server and
a client.
The client application makes a request by identifying the desired Internet
resource and the communication protocol that will be used to exchange the
request and response. If necessary, the client application also specifies any
additional data that is required to complete the request, such as proxy location
or authentication information. Authentication information includes such
information as user name and password. When the request is formed, it can be
sent to the server.
After the server has received the request and processed the response, the
response is returned to the client application. The response includes information
that supplements the contents of the response, such as the type of content,
which may include raw text or XML data.
4 Module 11: Internet Access

The .NET Framework provides classes that can be used to implement a

request/response model to access Internet resources. The two principal classes
are the WebRequest class, which contains a request for the resource; and the
WebResponse class, which provides a container for the incoming response. In
addition, the Uri class is used to contain a Uniform Resource Identifier (URI),
which identifies the Internet resource that you are seeking. The
NetworkStream class is used to write and read the data.

Note A Uniform Resource Identifier URI is a compact representation of a

resource that is available to your application through the Internet. You may be
more familiar with the term, URL, which stands for Uniform Resource Locator.
URLs form a subset of the more general URI naming scheme. A URL identifies
an Internet resource that has a Web page address.

For applications that need to make simple requests for Internet resources, the
WebClient class provides common methods for uploading data to or
downloading data from an Internet server. WebClient relies on the
WebRequest class to provide access to Internet resources; therefore, the
WebClient class can use any registered pluggable protocol.
Module 11: Internet Access 5

Uniform Resource Identifier

Topic Objective
To introduce the four parts
of the URI. ! URI Contains:

Lead-in " Scheme identifier – specifies protocol to be used

The .NET Framework uses " Server identifier – specifies DNS name or TCP address
the URI to identify the
" Path identifier – specifies location on the server
desired communication
protocol and Internet " Optional query string – provides additional request information
resource.
! Example: http://www.contoso.com/whatsnew.aspx?date=today
" Scheme identifier – http
" Server identifier – www.contoso.com
" Path identifier – /whatsnew.aspx
" Query String – ?date=today

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework uses the URI to identify the desired communication
protocol and Internet resource.
The URI consists of at least three, and possibly four, parts:
! The scheme identifier, which identifies the communications protocol that is
used by the request and response
! The server identifier, which consists of a Domain Name System (DNS) host
name or TCP address that uniquely identifies the server on the Internet
! The path identifier, which locates the requested information on the server
! An optional query string, which passes information from the client to the
server

For example, the URI http://www.contoso.com/whatsnew.aspx?date=today

consists of the scheme identifier http, the server identifier www.contoso.com,
the path identifier /whatsnew.aspx, and the query string ?date=today.
6 Module 11: Internet Access

NetworkStream Class
Topic Objective ! A NetworkStream Object Provides:
To explain the function of
Network streams in the " A Way to Send and Receive All Types of Web Data
.NET Framework. " Methods That Are Compatible with Other .NET Streams
Lead-in " Processing of Data As It Arrives
When resources on the
Internet are obtained by ! System.Text.Encoding – Characters from and to Bytes
using the System.Net
//
// reading
reading ASCII
ASCII stream
stream to
to string
string
classes, the data that is
Byte[] read = new Byte[32];
Byte[] read = new Byte[32];
being sent and received is
int
int bytes
bytes == anASCIIStream1.Read(read,
anASCIIStream1.Read(read, 0, 0, read.Length);
read.Length);
represented through a string
Stream object. string stringData
stringData == Encoding.ASCII.GetString(read);
Encoding.ASCII.GetString(read);
//
// writing
writing string
string to
to ASCII
ASCII stream
stream
Byte[]
Byte[] asciiBytes
asciiBytes == Encoding.ASCII.GetBytes(stringData);
Encoding.ASCII.GetBytes(stringData);
anASCIIStream2.Write(asciiBytes,
anASCIIStream2.Write(asciiBytes, 0, 0, asciiBytes.Length);
asciiBytes.Length);

! Sequential Blocks Use StreamReader and StreamWriter

*ILLEGAL FOR NON-TRAINER USE**

When resources on the Internet are obtained by using the System.Net classes, a
Stream object represents the data that is being sent and received.
Streams provide:
! A common way to send and receive Web data.
Whether the actual contents of the file are HTML, XML, or another format,
an application uses Stream.Write and Stream.Read to send and receive
byte data.
! Compatibility with streams across the .NET Framework.
Streams are used throughout the .NET Framework, which provides a rich
infrastructure for handling them. For example, by changing only the few
lines of code that initialize the stream, you can modify an application that
reads XML data from a file stream to read data from a network stream
instead.
The major differences between the NetworkStream class and other streams
are that the NetworkStream class is not seekable, the CanSeek property
always returns false, and the Seek and Position methods throw a
NotSupportedException.
! Processing of data as it arrives.
Streams provide access to data as it arrives from the Internet, rather than
forcing your application to wait for an entire data set to be downloaded.
Module 11: Internet Access 7

Conversion Between Characters and Bytes

The System.Text namespace contains classes for converting blocks of
characters to and from blocks of bytes. In particular, the Encoding class has
methods to convert arrays and strings of Unicode characters to and from arrays
of bytes, as in the following example:
// variable named anASCIIStream1 of type Stream
// has been previously assigned to a Stream
// containing bytes representing 7 bit ASCII character
//
// reading ASCII stream and converting to string
Byte[] read = new Byte[32];
int bytes = anASCIIStream1.Read(read, 0, read.Length);
string stringData = Encoding.ASCII.GetString(read);
// ...
// variable named anASCIIStream2 of type Stream
// has been previously assigned to a writable Stream
//
// converting string and writing 7 bit ASCII characters
Byte[] asciiBytes =
Encoding.ASCII.GetBytes(stringData);
anASCIIStream2.Write(asciiBytes, 0, asciiBytes.Length);

Converting Data from Sequential Blocks

When the data that must be converted is only available in sequential blocks,
such as data that is read from a long stream, an application may choose to use a
decoder or an encoder to perform the conversion. However, you can use the
StreamReader and StreamWriter classes to facilitate decoding and encoding
characters, as in the following example:
// variable anASCIIStream has been previously assigned
// to a Stream of ASCII bytes
StreamReader sr = new StreamReader(
anASCIIStream,Encoding.ASCII);

int length = 1024;

char[] Buffer = new char[1024];
int bytesread = 0;

//Read from the stream and write data to console

bytesread = sr.Read( Buffer, 0, length);
while( bytesread > 0 ) {
Console.Write( Buffer,0, bytesread);
bytesread = sr.Read( Buffer, 0, length);
}

//Close the stream when finished

sr.Close();
8 Module 11: Internet Access

Creating a WebRequest
Topic Objective ! The WebRequest Encapsulates Details of Request
To describe how client
applications use the " Created by calling WebRequest.Create method
WebRequest.
WebRequest
WebRequest req
req ==
Lead-in WebRequest.Create("http://www.contoso.com/");
Client applications request WebRequest.Create("http://www.contoso.com/");
data from servers by using
the WebRequest class and " Set any property values that are required
its descendents. req.Credentials
req.Credentials == new
new
NetworkCredential("username","password");
NetworkCredential("username","password");

" Cast to access protocol-specific features

HttpWebRequest
HttpWebRequest httpReq
httpReq == (HttpWebRequest)
(HttpWebRequest)
WebRequest.Create("http://www.contoso.com/");
WebRequest.Create("http://www.contoso.com/");
//
// Turn
Turn off
off connection
connection keep-alives.
keep-alives.
httpReq.KeepAlive
httpReq.KeepAlive == false;
false;

*ILLEGAL FOR NON-TRAINER USE**

Client applications request data from servers by using the WebRequest class
and its descendents. The WebRequest class encapsulates the details of the
process of connecting to the server, sending the request, and receiving the
response.

Calling WebRequest.Create
Applications create WebRequest instances through the static
WebRequest.Create method. WebRequest.Create is a static method that
creates a descendent WebRequest instance that is based on the URI scheme
that is passed.
For example, the following code creates an HTTP request to
www.contoso.com:
WebRequest req =
WebRequest.Create("http://www.contoso.com/");

Setting Required Property Values

Clients set required property values in the WebRequest instance. For example,
to support authentication, you can set the Credentials property to an instance of
the NetworkCredential class, as shown in the following code:
req.Credentials = new
NetworkCredential("username","password");
Module 11: Internet Access 9

Casting WebRequest Objects to HttpWebRequest

To handle HTTP protocol requests to the Internet, the .NET Framework
provides an HttpWebRequest class that is derived from the WebRequest
class. In most cases, the WebRequest class provides all of the properties that
you need to make a request. However, if you need to access the HTTP
protocol-specific properties of the request, you can typecast WebRequest
objects that are created by the WebRequest.Create to HttpWebRequest, as in
the following example:
HttpWebRequest httpReq = (HttpWebRequest)
WebRequest.Create("http://www.contoso.com/");

// Turn off connection keep-alives.

httpReq.KeepAlive = false;

Supporting Additional Protocols

The .NET Framework provides protocol-specific WebRequest and
WebResponse descendants for URIs that begin with http:, https:, and file:.
The programmable pluggable protocols of System.Net allow applications to
provide access through other protocols. To support additional protocols, you
should implement protocol-specific descendants of WebRequest and
WebResponse and register the descendant’s constructor with the
WebRequest.RegisterPrefix method.
For more information about supporting additional protocols, see the .NET
Framework Software Development Kit (SDK) documentation.
10 Module 11: Internet Access

Invoking a WebRequest
Topic Objective
To explain how to invoke the
request for an Internet
resource by calling the ! Request Is Made by Calling the GetResponse Method
GetResponse method on
the WebRequest instance. WebResponse
WebResponse resp
resp == req.GetResponse();
req.GetResponse();
Lead-in
After creating the
WebRequest, you invoke " Cast to access HTTP-specific features
the request for the Internet
resource by calling the HttpWebResponse
HttpWebResponse httpResp
httpResp ==
GetResponse method on (HttpWebResponse)httpReq.GetResponse();
(HttpWebResponse)httpReq.GetResponse();
the WebRequest instance.
//Get
//Get the
the HTTP
HTTP content
content length
length returned
returned by
by the
the server.
server.
String contentLength
String contentLength = =
httpResp.ContentLength.ToString();
httpResp.ContentLength.ToString();

*ILLEGAL FOR NON-TRAINER USE**

After creating the WebRequest, you invoke the request for the Internet
resource by calling the GetResponse method on the WebRequest instance.
The GetResponse method is responsible for:
! Constructing the protocol-specific request from the properties of the
WebRequest instance.
! Making the TCP or UDP socket connection to the server.
! Sending the request.

The GetResponse method returns an instance that is derived from

WebResponse that matches the instance that is derived from WebRequest, as
in the following example:
WebResponse resp = req.GetResponse();

The WebResponse class is also an abstract class that defines properties and
methods that are available to all applications that use pluggable protocols.
WebResponse descendents are responsible for implementing these properties
and methods for the underlying protocol.
For example, the HttpWebResponse class implements the WebResponse class
for the HTTP protocol. If you need to access the HTTP protocol-specific
properties of the response, you can typecast WebResponse objects to
HttpWebResponse, as in the following example:
HttpWebResponse httpResp =
(HttpWebResponse)httpReq.GetResponse();

//Get the HTTP content length returned by the server.

String contentLength = httpResp.ContentLength.ToString();
Module 11: Internet Access 11

Sending Data
Topic Objective ! For Requests That Send Data to the Server
To describe how requests
that send data to the server //
are created. // ...
...
try
try
Lead-in {{
For requests that send data byte[]
byte[] sendData
sendData ==
Encoding.ASCII.GetBytes("some
Encoding.ASCII.GetBytes("some data");
data");
to the server, such as
int
int sendLength
sendLength == sendData.Length;
sendData.Length;
HTTP-POST or FTP-PUT
HttpWebRequest
HttpWebRequest httpReq
httpReq ==
requests, the data is sent (HttpWebRequest)
through a network stream (HttpWebRequest) WebRequest.Create(
WebRequest.Create(
"http://www.contoso.com/");
"http://www.contoso.com/");
that is provided by the httpReq.Method
httpReq.Method == "POST";
"POST";
WebRequest.GetRequest httpReq.ContentLength
httpReq.ContentLength == sendLength;
sendLength;
Stream method. Stream
Stream sendStream
sendStream == httpReq.GetRequestStream();
httpReq.GetRequestStream();
sendStream.Write(sendData,0,sendLength);
sendStream.Write(sendData,0,sendLength);
sendStream.Close();
sendStream.Close();
}}
catch(Exception
catch(Exception e)
e) {//...}
{//...} //...
//...

*ILLEGAL FOR NON-TRAINER USE**

For requests that send data to the server, such as HTTP-POST or FTP-PUT
requests, the data is sent through a network stream that is provided by the
WebRequest.GetRequestStream method. You use the resulting Stream
object to write the data. When you have finished uploading, you must close the
request stream with the Stream.Close method.
The following example shows how to create a request that uses HTTP-POST to
send data to the server:
// ...
try
{
byte[] sendData = Encoding.ASCII.GetBytes("some data");
int sendLength = sendData.Length;
HttpWebRequest httpReq =
(HttpWebRequest) WebRequest.Create(
"http://www.contoso.com/");
httpReq.Method = "POST";
httpReq.ContentLength = sendLength;
Stream sendStream = httpReq.GetRequestStream();
sendStream.Write(sendData,0,sendLength);
sendStream.Close();
}
catch(Exception e)
{//...
}
//...

After closing the stream, you can call GetResponse to ensure that the server
received the data correctly.
12 Module 11: Internet Access

Receiving Data
Topic Objective
To explain how to obtain the
! Reading Response Data
stream that contains
response data from the
network. //
// Get
Get the
the response
response stream.
stream.
Stream
Stream respstrm == resp.GetResponseStream();
respstrm resp.GetResponseStream();
Lead-in //
// Create
Create aa buffer
buffer to to hold
hold the
the response
response data.
data.
To obtain the stream that int BufferSize = 512;
int BufferSize = 512;
contains response data from Byte[]
the network resource, use Byte[] Buffer
Buffer == new
new Byte[BufferSize];
Byte[BufferSize];
//
// Read
Read the
the stream
stream to to access
access the
the data.
data.
the GetResponseStream int
method of the int bytesRead
bytesRead == respstrm.Read(Buffer,
respstrm.Read(Buffer, 0, 0, BufferSize);
BufferSize);
while (bytesRead >
while (bytesRead > 0) { 0) {
WebResponse instance.
Console.Write(
Console.Write(
Encoding.ASCII.GetString(Buffer,
Encoding.ASCII.GetString(Buffer, 0, 0, bytesRead));
bytesRead));
bytesRead
bytesRead = respstrm.Read(Buffer, 0, BufferSize);
= respstrm.Read(Buffer, 0, BufferSize);
}}
respstrm.Close();
respstrm.Close();

*ILLEGAL FOR NON-TRAINER USE**

To obtain the stream that contains response data from the network resource, use
the GetResponseStream method of the WebResponse instance, as in the
following example:
// Get the response stream.
Stream respstrm = resp.GetResponseStream();
// Create a buffer to hold the response data.
int BufferSize = 512;
Byte[] Buffer = new Byte[BufferSize];
// Read the stream to access the data.
int bytesRead = respstrm.Read(Buffer, 0, BufferSize);
while (bytesRead > 0) {
Console.Write(
Encoding.ASCII.GetString(Buffer, 0, bytesRead));
bytesRead = respstrm.Read(Buffer, 0, BufferSize);
}
respstrm.Close();

If your application requires only the header information that is returned in the
WebResponse and ignores any returned data, then you do not need to get the
response stream.

Closing Responses
After reading the data from the response, you must close any opened stream by
using the Stream.Close method or close the response by using the
WebResponse.Close method, as in the following example:
resp.Close();
Module 11: Internet Access 13

You do not have to call the Close method on both the response stream and the
WebResponse instance, but it is recommended. WebResponse.Close calls
Stream.Close when it closes the response. If you do not close each response,
your application will run out of connections to the server and be unable to
process additional requests.

Considerations for Working with NetworkStreams

When using streams from network resources, remember the following:
! Because the NetworkStream class cannot change position in the stream, the
CanSeek property always returns false. The Seek and Position methods
throw a NotSupportedException.
! When you use WebRequest and WebResponse, stream instances that are
created by calling GetResponseStream are read-only, and stream instances
that are created by calling GetRequestStream are write-only.
! The call to GetResponse may block if network resources are not available.
You should consider using an asynchronous request with the
BeginGetResponse and EndGetResponse methods.
! The call to GetRequestStream may block while the connection to the
server is created.
You should consider using an asynchronous request for the stream with the
BeginGetRequestStream and EndGetRequestStream methods.
Asynchronous operations are beyond the scope of this course.
! You can use the StreamReader class to make the task of encoding easier.
The following code example uses a StreamReader to read an ASCII-
encoded stream from a WebResponse instance. The creation of the request
is not shown.
// Create a response object.
WebResponse response = request.GetResponse();
// Get a readable stream from the server.
StreamReader sr =
new StreamReader(
response.GetResponseStream(), Encoding.ASCII);
// Use the stream. Remember when you are through
// with the stream to close it
//...
sr.Close();
14 Module 11: Internet Access

Using the WebRequest and WebResponse Model

Topic Objective //...
//...
To provide an example of WebRequest
WebRequest wReq
wReq == WebRequest.Create
WebRequest.Create
the WebRequest and ("http://localhost/postinfo.html");
("http://localhost/postinfo.html");
WebResponse model. WebResponse
WebResponse wResp
wResp == wReq.GetResponse();
wReq.GetResponse();
//
// Get
Get aa readable
readable stream
stream from
from the
the server
server
Lead-in StreamReader
StreamReader sr sr == new
new StreamReader(
StreamReader(
You will now see an wResp.GetResponseStream(),Encoding.ASCII);
wResp.GetResponseStream(),Encoding.ASCII);
example of the use of the int
int length
length == 1024;
1024;
WebRequest and char[]
char[] Buffer
Buffer == new
new char[1024];
char[1024];
WebResponse model as int
int bytesread
bytesread == 0;0;
discussed in this section. //Read
//Read from
from the
the stream
stream and
and write
write data
data to
to console
console
bytesread
bytesread == sr.Read(
sr.Read( Buffer,
Buffer, 0,0, length);
length);
while(
while( bytesread
bytesread >> 00 )) {{
Console.Write(
Console.Write( Buffer,0,
Buffer,0, bytesread);
bytesread);
bytesread
bytesread == sr.Read(
sr.Read( Buffer,
Buffer, 0,0, length);
length);
}}
//Close
//Close the
the stream
stream when
when finished
finished
sr.Close();
sr.Close();
//...
//...
*****************************ILLEGAL FOR NON-TRAINER USE******************************
The following code example fully demonstrates the use of the WebRequest
and WebResponse model as discussed in this section:
using System;
using System.Net;
using System.IO;
using System.Text;

class App
{
public static void Main(string[] args)
{
try
{
WebRequest wReq = WebRequest.Create
("http://localhost/postinfo.html");
WebResponse wResp = wReq.GetResponse();

// Get a readable stream from the server

StreamReader sr = new StreamReader(
wResp.GetResponseStream(),Encoding.ASCII);

int length = 1024;

char[] Buffer = new char[1024];
int bytesread = 0;

(Code continued on the following page.)

Module 11: Internet Access 15

//Read from the stream and write data to console

bytesread = sr.Read( Buffer, 0, length);
while( bytesread > 0 )
{
Console.Write( Buffer,0, bytesread);
bytesread = sr.Read( Buffer, 0, length);
}

//Close the stream when finished

sr.Close();
}

catch(Exception e)
{
Console.WriteLine(
"\r\nThe request URI could not be found or was!
malformed:\n {0}",
e.ToString());
}
}
}
16 Module 11: Internet Access

# Application Protocols
Topic Objective
To introduce the topics in
the section.
! HTTP
Lead-in
The .NET Framework ! Internet Domain Name System
supports application
protocols that are currently ! TCP and UDP
in common use on the
Internet. ! Sockets

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework supports application protocols that are currently in
common use on the Internet.
This section provides information about using the HTTP, TCP, and UDP
protocol support that is provided in the .NET Framework, in addition to
information about using the Windows Sockets interface to implement custom
protocols.
Module 11: Internet Access 17

HTTP
Topic Objective
To describe the support that
the .NET Framework
provides for the HTTP ! Classes That Provide HTTP and HTTPS Protocols
protocol.
" HttpWebRequest and HttpWebResponse
Lead-in
With the HttpWebRequest ! Support Most HTTP 1.1 features
and HttpWebResponse
classes, the .NET ! HTTP Redirects Automatically if AllowAutoRedirect
Framework provides Property Is true (the Default)
comprehensive support for
the HTTP protocol, which ! Use ServicePoint, ServicePointManager, and
makes up the majority of all ConnectionGroupName Classes to Manage Connections
Internet traffic.

*ILLEGAL FOR NON-TRAINER USE**

With the HttpWebRequest and HttpWebResponse classes, the .NET
Framework provides comprehensive support for the HTTP protocol, which
makes up the majority of all Internet traffic.

Classes for the HTTP and HTTPS Protocols

The HttpWebRequest and HttpWebResponse classes are derived from the
WebRequest and WebResponse classes, as was described in Creating a
WebRequest in this module. HttpWebRequest and HttpWebResponse are
returned by default whenever the static method WebRequest.Create
encounters a URI that begins with http or https.
In most cases, the WebRequest and WebResponse classes provide all that is
necessary to make the request, but if you need access to the HTTP-specific
features that are exposed as properties, you can typecast these classes to
HttpWebRequest or HttpWebResponse, as demonstrated in Creating a
WebRequest in this module.

Note Do not use the HttpWebRequest constructor. Use the

WebRequest.Create method to initialize new HttpWebRequest instances. If
the scheme for the URI is http:// or https://, Create returns an
HttpWebRequest instance.

Support for HTTP 1.1 Features

The HttpWebRequest and HttpWebResponse classes encapsulate a standard
HTTP request/response transaction and provide access to common HTTP
headers. These classes also support most HTTP 1.1 features, including
pipelining, chunking, authentication, pre-authentication, encryption, proxy
support, server certificate validation, and connection management. Custom
headers and headers that are not provided through properties can be stored in
and accessed through the Headers property.
18 Module 11: Internet Access

Support for HTTP Redirects

You can make your application follow HTTP redirects automatically by setting
the AllowAutoRedirect property to true, which is the default value. The
application redirects requests, and the ResponseURI property of
HttpWebResponse contains the actual Internet resource that responds to the
request. If you set AllowAutoRedirect to false, your application must be able
to handle redirects as HTTP protocol errors.
Applications receive HTTP protocol errors by catching a WebException with
the value of the Status property set to WebExceptionStatus.ProtocolError.
The Response property contains the WebResponse that is sent by the server
and indicates the actual HTTP error that is encountered.

Managing Internet Connections

Applications that use HTTP to connect to data resources can use the .NET
Framework ServicePoint and ServicePointManager classes to manage the
number of connections to the Internet and to optimize scale and performance.
The number of connections between a client and server can have a dramatic
effect on application throughput.
You can use ConnectionGroupName to form connection grouping that
associates specific requests within a single application to a defined connection
pool. You may have to use this technique with a middle-tier application that
connects to a back-end server on behalf of a user and uses an authentication
protocol that supports delegation, such as Kerberos, or by a middle-tier
application that supplies its own credentials.
For more information about classes that are used to manage connections and
their methods, see the .NET Framework SDK documentation.
Module 11: Internet Access 19

Internet Domain Name System

Topic Objective
To explain how to use the
Dns class to retrieve
information about a host. ! Dns Class Retrieves Data About a Host from DNS
Lead-in " GetHostByName query for www.contoso.com
The Dns class is a static
class that retrieves IPHostEntry
IPHostEntry hostInfo
hostInfo ==
information about a specific Dns.GetHostByName("www.contoso.com");
Dns.GetHostByName("www.contoso.com");
host from the Internet
Domain Name System.
" Resolve query for www.contoso.com
IPHostEntry
IPHostEntry hostInfo
hostInfo ==
Dns.Resolve("www.contoso.com");
Dns.Resolve("www.contoso.com");

*ILLEGAL FOR NON-TRAINER USE**

The Dns class is a static class that retrieves information about a specific host
from the Internet Domain Name System (DNS).
The host information from a GetHostByName query is returned in an instance
of the IPHostEntry class. If the specified host has more than one entry in the
DNS database, IPHostEntry contains multiple Internet Protocol (IP) addresses
and aliases.
The following example queries the DNS database for information about a host
that is called www.contoso.com:
IPHostEntry hostInfo = Dns.GetHostByName("www.contoso.com");

The Resolve method queries a DNS server for the IP address that is associated
with a host name, such as www.contoso.com, or for an IP address in
dotted-quad notation, such as 192.168.1.2.
When the host name is a DNS-style host name that is associated with multiple
IP addresses, only the first IP address that resolves to that host name is returned,
as in the following example:
IPHostEntry hostInfo = Dns.Resolve("www.contoso.com");
20 Module 11: Internet Access

TCP and UDP

Topic Objective
To explain how to use the ! TCP Client Connecting to a Server/Listener
TcpClient and TcpListener TcpClient
classes to request data from TcpClient tcpc
tcpc == new
new TcpClient(serverURI,
TcpClient(serverURI, 14);
14);
Stream
Stream ss == tcpc.GetStream();
tcpc.GetStream();
an Internet resource and to
Byte[]
Byte[] read
read == new
new Byte[32];
Byte[32];
monitor TCP ports.
int
int bytes = s.Read(read, 0,
bytes = s.Read(read, 0, read.Length);
read.Length);
Lead-in String strInData = Encoding.ASCII.GetString(read);
String strInData = Encoding.ASCII.GetString(read);
Applications can use TCP
and UDP services with the ! TCP Server/Listener Monitors Port for Clients
TcpClient, TcpListener, TcpListener
TcpListener tcpl
tcpl == new
new TcpListener(14);
TcpListener(14);
and UdpClient classes. tcpl.Start();
tcpl.Start();
while
while (!done)
(!done) {{
//
// Accept will block until
Accept will block until someone
someone connects
connects
Socket s = tcpl.AcceptSocket();
Socket s = tcpl.AcceptSocket();
//Code
//Code to
to handle
handle request
request goes
goes here
here
}}
tcpl.Stop();
tcpl.Stop();
*****************************ILLEGAL FOR NON-TRAINER USE******************************
Applications can use TCP and UDP services with the TcpClient, TcpListener,
and UdpClient classes. These classes, which are built on top of the Socket
class, represent the data that is sent and received from the network as streams.
These classes also take care of the details of creating a connection.

Using the TcpClient Class

You use the TcpClient class to request data from an Internet resource that uses
TCP. The methods and properties of TcpClient abstract the details for creating
a Socket instance that requests and receives data through TCP. The connection
to the Internet is represented as a stream; therefore data can be read and written
in a standard manner.
The following code demonstrates how to set up a TcpClient object to connect
to a server on TCP port 14:
TcpClient tcpc = new TcpClient(serverURI, 14);
Stream s = tcpc.GetStream();
Byte[] read = new Byte[32];
int bytes = s.Read(read, 0, read.Length);
String strInData = Encoding.ASCII.GetString(read);
Module 11: Internet Access 21

Using the TcpListener Class

You use a TcpListener object to monitor a TCP port for incoming requests and
then create a Socket instance that manages the connection to the client. The
Start method enables listening, and the Stop method disables listening on the
port. The AcceptSocket method accepts incoming connection requests and
creates the socket that will handle the request.
The following code demonstrates how to set up a TcpListener object to
monitor TCP port 14:
TcpListener tcpl = new TcpListener(14); // listen on port 14
tcpl.Start();
while (!done) {
// Accept will block until someone connects
Socket s = tcpl.AcceptSocket();
//Code to handle request goes here
}
tcpl.Stop();
22 Module 11: Internet Access

Sockets
Topic Objective
To describe the Socket
class and provide an
example of how the Socket ! System.Net Classes Are Built on System.Net.Sockets
class can be used to send
! System.Net.Sockets Are Based on the WinSock32 API
data to an HTTP server and
to receive the response. ! See Example in Student Notes
Lead-in
The System.Net.Sockets
namespace contains an
implementation of the
Windows Sockets
interface.

*ILLEGAL FOR NON-TRAINER USE**

The System.Net.Sockets namespace contains an implementation of the
Windows Sockets interface. All other network access classes in the
System.Net namespace are built on top of this implementation of sockets.
The .NET Framework’s Socket class is a managed code version of the socket
services that are provided by the WinSock32 API. If you are familiar with the
Winsock API, you should be comfortable using the Socket class to develop
applications. In most cases, the Socket class methods simply marshal data into
their native Microsoft Win32® counterparts and handle necessary security
checks.
Module 11: Internet Access 23

The following example shows how the Socket class can be used to send data to
an HTTP server and receive the response:
using System;
using System.Net;
using System.Net.Sockets;
using System.IO;
using System.Text;

class App
{
public static void Main(string[] args)
{
DoSocketGet("localhost");
}
public static string DoSocketGet(string server)
{
//Set up variables and String to write to the server
Encoding ASCII = Encoding.ASCII;
string Get = "GET / HTTP/1.1\r\nHost: " + server +
"\r\nConnection: Close\r\n\r\n";
Byte[] ByteGet = ASCII.GetBytes(Get);
Byte[] RecvBytes = new Byte[256];
String strRetPage = "";

// IPHostEntry and IPEndPoint

// represent the endpoint that
// will receive the request
IPHostEntry hostEntry = Dns.Resolve(server);
IPEndPoint EPhost = new
IPEndPoint(hostEntry.AddressList[0], 80);

//Create the Socket for sending data over TCP

Socket mySocket = new Socket(AddressFamily.InterNetwork,
SocketType.Stream, ProtocolType.Tcp );
// Connect to host using IPEndPoint
try
{
mySocket.Connect(EPhost);
// Sent the GET text to the host
mySocket.Send(ByteGet, ByteGet.Length, 0);

// Receive the page, loop until all received

Int32 bytes = mySocket.Receive(RecvBytes,
RecvBytes.Length, 0);
strRetPage = "Default HTML page on " + server +
":\r\n";
strRetPage = strRetPage + ASCII.GetString(RecvBytes,
0, bytes);

(Code continued on the following page.)

24 Module 11: Internet Access

while (bytes > 0)

{
bytes = mySocket.Receive(RecvBytes,
RecvBytes.Length, 0);
strRetPage = strRetPage +
ASCII.GetString(RecvBytes, 0,
bytes);
}
}
catch (Exception e)
{
Console.WriteLine("Exception {0}",e.ToString());
}
return strRetPage;
}
}
Module 11: Internet Access 25

Handling Errors
Topic Objective ! A WebException Can Be Thrown by GetResponse
To explain how the Status
property is used to " Has Status property, value from WebExceptionStatus
determine if an error has " If WebExceptionStatus.ProtocolError, then WebResponse
occurred. contains protocol error information
Lead-in try
try
The WebRequest and {{ // // ...
... Create
Create aa request,
request, get
get response
response and
and process
process stream.
stream. }}
WebResponse classes catch
catch (WebException
(WebException webExcp)
webExcp)
{{
throw system exceptions Console.WriteLine("A
Console.WriteLine("A WebException
WebException has
has been
been caught");
caught");
and Web-specific Console.WriteLine(webExcp.ToString());
Console.WriteLine(webExcp.ToString());
exceptions, which are WebExceptionStatus
WebExceptionStatus status
status == webExcp.Status;
webExcp.Status;
instances of WebException if
if (status
(status ==
== WebExceptionStatus.ProtocolError)
WebExceptionStatus.ProtocolError) {{
and thrown by the Console.Write(
Console.Write(
"The
"The server
server returned
returned protocol
protocol error
error ");
");
GetResponse method. Console.WriteLine(webExcp.Response.ToString());
Console.WriteLine(webExcp.Response.ToString());
}}
}}
catch
catch (Exception
(Exception e)e)
{//
{// Code
Code to
to catch
catch other
other exceptions
exceptions goes
goes here.}
here.}
*****************************ILLEGAL FOR NON-TRAINER USE******************************
The WebRequest and WebResponse classes throw system exceptions, such as
InvalidArgumentException, and Web-specific exceptions, which are instances
of WebException and are thrown by the GetResponse method.
Each WebException includes a Status property that contains a value from the
WebExceptionStatus class. You can examine the Status property to determine
the particular error that has occurred and take the proper steps to resolve the
error.
The following table describes some of the possible values for the Status
property. For a complete list of values, see the .NET Framework SDK
documentation.
Value Description

ConnectFailure The remote service could not be contacted at the

transport level.
ConnectionClosed The connection was closed prematurely.
KeepAliveFailure The server closed a connection made with the Keep-alive
header set.
NameResolutionFailure The name service could not resolve the host name.
ProtocolError The response received from the server was complete but
indicated an error at the protocol level.
ReceiveFailure A complete response was not received from the remote
server.
RequestCanceled The request was canceled.
SecureChannelFailure An error occurred in a secure channel link.
SendFailure A complete request could not be sent to the remote
server.
26 Module 11: Internet Access

(continued)
Value Description

ServerProtocolViolation The server response was not a valid HTTP response.

Success No error was encountered.
Timeout No response was received within the time-out set for the
request.
TrustFailure A server certificate could not be validated.

When the Status property is WebExceptionStatus.ProtocolError, a

WebResponse that contains the response from the server is available. You can
examine this response to determine the actual source of the protocol error.
The following example shows how to catch a WebException; the invalid URL
argument in the WebRequest.Create call will throw an exception:
using System;
using System.Net;
using System.IO;
using System.Text;

class App
{
public static void Main(string[] args)
{
try
{
// Create a request instance
// Note invalid URL will throw exception
WebRequest myRequest =
WebRequest.Create("http://localhost_bad_URL");

// Get the response.

WebResponse myResponse = myRequest.GetResponse();

//Get a readable stream from the server.

StreamReader sr = new StreamReader(
myResponse.GetResponseStream(), Encoding.ASCII);

int length = 1024;

char [] Buffer = new char[1024];
int bytesread = 0;
//Read from the stream and write data to Console.
bytesread = sr.Read( Buffer, 0, length);
while( bytesread > 0 )
{
Console.Write( Buffer, 0, bytesread);
bytesread = sr.Read( Buffer, 0, length);
}
sr.Close();
myResponse.Close();
}
(Code continued on the following page.)
Module 11: Internet Access 27

catch (WebException webExcp)

{
Console.WriteLine("A WebException has been caught");
// Write out the WebException message.
Console.WriteLine(webExcp.ToString());
// Get the WebException status code.
WebExceptionStatus status = webExcp.Status;
// If status is WebExceptionStatus.ProtocolError,
// there has been a protocol error and a
// WebResponse should exist.
// Display the protocol error.
if (status == WebExceptionStatus.ProtocolError)
{
Console.Write(
"The server returned protocol error ");
Console.WriteLine(webExcp.Response.ToString());
}
}
catch (Exception e)
{
// Code to catch other exceptions goes here.
}

}
}

Applications that use the Socket class throw instances of SocketException

when errors occur on the Windows socket. The TcpClient, TcpListener, and
UdpClient classes are built on top of the Socket class and also throw instances
of SocketException.
When a SocketException is thrown, the Socket class sets the ErrorCode
property to the last operating system socket error that occurred.
28 Module 11: Internet Access

# Security
Topic Objective
To introduce the topics in
the section.
! Web Proxy
Lead-in
Your application can provide ! Secure Sockets Layer
security for sending and
receiving data over the ! Internet Authentication
Internet by using a Web
proxy, SSL encryption, ! Permissions
Internet authentication, and
the NET Framework’s code
access permissions.

*ILLEGAL FOR NON-TRAINER USE**

Your application can provide security for sending and receiving data over the
Internet by using a Web proxy, Secure Sockets Layer (SSL) encryption,
Internet authentication, and the NET Framework’s code access permissions.
Module 11: Internet Access 29

Web Proxy
Topic Objective
To show how to use a Web ! Global Proxy for All Web Requests
proxy to communicate with
the Internet.
" Proxy named webproxy using port 80
Lead-in
WebProxy
WebProxy proxyObject
proxyObject == new
new WebProxy(
WebProxy(
If your Web site uses a
proxy to provide access to "http://webproxy:80/");
"http://webproxy:80/");
the Internet, you must GlobalProxySelection.Select
GlobalProxySelection.Select == proxyObject;
proxyObject;
configure a proxy instance
to enable your application to
! Overriding the Global Proxy Setting
communicate with the Web
proxy. " Request uses proxy named alternateproxy and port 80
WebRequest
WebRequest req
req == WebRequest.Create(
WebRequest.Create(
"http://www.contoso.com/");
"http://www.contoso.com/");
req.Proxy
req.Proxy == new
new WebProxy(
WebProxy(
"http://alternateproxy:80/");
"http://alternateproxy:80/");
*****************************ILLEGAL FOR NON-TRAINER USE******************************
If your Web site uses a proxy to provide access to the Internet, you must
configure a proxy instance to enable your application to communicate with the
Web proxy.

Creating a Global Proxy Instance

The following example shows how to create a global proxy instance that
enables any WebRequest to use a proxy to communicate with the Internet. The
example assumes that the proxy server is named webproxy and that it
communicates on port 80, the standard HTTP port.
WebProxy proxyObject = new WebProxy("http://webproxy:80/");
GlobalProxySelection.Select = proxyObject;

Overriding the Global Proxy Selection

You can override the global proxy selection by assigning an instance that
implements the IWebProxy interface to the Proxy property of the
WebRequest. The following code sends a WebRequest to
http://www.contoso.com. The WebRequest overrides the global proxy
selection with a proxy server that is named alternateproxy on port 80.
WebRequest req = WebRequest.Create("http://www.contoso.com/");
req.Proxy = new WebProxy("http://alternateproxy:80/");
30 Module 11: Internet Access

Secure Sockets Layer

Topic Objective
To explain how SSL is used
for secure network
communication. ! SSL Is Used Automatically If the URI Begins with https
Lead-in
The WebRequest and
String
String MyURI
MyURI == "https://www.contoso.com/";
"https://www.contoso.com/";
WebResponse classes use
WebRequest
WebRequest wReq
wReq == WebRequest.Create(MyURI);
WebRequest.Create(MyURI);
SSL automatically.

*ILLEGAL FOR NON-TRAINER USE**

The WebRequest and WebResponse classes use SSL automatically. The
WebRequest object decides to use SSL on the basis of the URI that it is
assigned. If the URI begins with https:, SSL is used. If the URI begins with
http:, SSL is not used.
The following example illustrates the use of SSL:
String MyURI = "https://www.contoso.com/";
WebRequest wReq = WebRequest.Create(MyURI);
Module 11: Internet Access 31

Internet Authentication
Topic Objective
To introduce the client
authentication mechanisms ! .NET Supports Various Kinds of Authentication
that are supported by the
System.Net classes. " Basic, digest, negotiate, NTLM, and Kerberos
authentication
Lead-in
The System.Net classes " Users can also create their own authentication
support a variety of client
authentication mechanisms,
! Credentials Stored in Classes
including the standard " NetworkCredential – for a single Internet resource
Internet authentication
methods: basic, digest, " CredentialCache – for multiple Internet resources
negotiate, NTLM, and
Kerberos authentication, ! Authentication Managed by the AuthenticationManager
and custom methods that
you can create.
! Some Schemes Allow Pre-Authentication to Save Time

*ILLEGAL FOR NON-TRAINER USE**

The System.Net classes support a variety of client authentication mechanisms,
including the standard Internet authentication methods: basic, digest, negotiate,
NTLM, and Kerberos authentication, and custom methods that you can create.

Classes and Interfaces Used for Authentication

Authentication credentials are stored in the NetworkCredential and
CredentialCache classes, which implement the ICredentialLookup interface.
When one of these classes is queried for credentials, it returns an instance of the
NetworkCredential class.
The AuthenticationManager class manages the authentication process, while
an authentication module class that implements the IAuthenticationModule
interface performs the actual authentication process. You must register a custom
authentication module with the AuthenticationManager before it can be used.
Modules for the basic, digest, negotiate, NTLM, and Kerberos authentication
methods are registered by default.

The NetworkCredential Class

The NetworkCredential class stores a set of credentials, which is associated
with a single Internet resource and that is identified by a URI, and returns them
in response to any call to the GetCredential method. The NetworkCredential
class is typically used by applications that access a limited number of Internet
resources or by applications that use the same set of credentials in all cases.

The CredentialCache Class

The CredentialCache class stores a collection of credentials for various
Internet resources. When the GetCredential method is called,
CredentialCache returns the proper set of credentials, as determined by the
URI of the Internet resource and the requested authentication scheme. Because
the CredentialCache class stores all of the credentials and provides them as
requested, applications that use a variety of Internet resources with different
authentication schemes benefit from using the CredentialCache class.
32 Module 11: Internet Access

The Authentication Process

When an Internet resource requests authentication, the
WebRequest.GetResponse method sends the WebRequest and the request for
credentials to the AuthenticationManager. The request is then authenticated
according to the following procedure:
1. The AuthenticationManager calls the Authenticate method on each of the
registered authentication modules in the order that they were registered.
2. The AuthenticationManager uses the first module that does not return null
to carry out the authentication process.
The details of the process vary depending on the type of authentication
module involved.
3. When the authentication process is complete, the authentication module
returns an Authorization instance to the WebRequest that contains the
information that is needed to access the Internet resource.

Some authentication schemes can authenticate a user without first making a

request for a resource. An application can save time by pre-authenticating the
user with the resource, thus eliminating at least one roundtrip to the server.
Alternatively, the application can perform authentication during program
startup to be more responsive to the user later. Authentication schemes that can
use pre-authentication set the CanPreAuthenticate property to true.

Basic and Digest Authentication

The System.Net implementation of basic and digest authentication complies
with RFC2617, “HTTP Authentication: Basic and Digest Authentication,”
which is available on the World Wide Web Consortium (W3C) Web site at
http://www.w3c.org.
To use basic and digest authentication, an application must provide a user name
and password in the Credentials property of the WebRequest object that it
uses to request data from the Internet, as shown in the following example:

Caution String literals in an application are stored and transported as clear text.
Therefore, you should avoid putting sensitive information such as passwords in
string literals.

// variables named username and password

// of type string have been previously assigned
String MyURI = "http://www.contoso.com/";
WebRequest wReq = WebRequest.Create(MyURI);
wReq.Credentials = new NetworkCredential(
username, password);
Module 11: Internet Access 33

NTLM and Kerberos Authentication

Default NTLM authentication and Kerberos authentication use the Microsoft
Windows NT® user credentials that are associated with the calling application
to attempt authentication with the server to pass the username, password, and
domain to the host, as in the following example:
// variables named username, password, and domain
// of type string have been previously assigned
String MyURI = "http://www.contoso.com/";
WebRequest wReq = WebRequest.Create(MyURI);
wReq.Credentials =
new NetworkCredential(username, password, domain);

Applications that need to connect to Internet services by using the credentials of

the application user can do so with the user’s default credentials, as in the
following example:
String MyURI = "http://www.contoso.com/";
WebRequest wReq = WebRequest.Create(MyURI);
wReq.Credentials = CredentialCache.DefaultCredentials;

The negotiate authentication module determines whether the remote server is

using NTLM or Kerberos authentication and sends the appropriate response.

Note NTLM authentication does not work through a proxy server.

Passport Authentication
Passport authentication is a centralized authentication service provided by
Microsoft that offers a single logon and core profile services for member sites.
This benefits the user because it is no longer necessary to log on to access new
protected resources or sites. If you want your site to be compatible with
Passport authentication and authorization, this is the provider you should use.
For more information, see the Passport documentation located at
http://www.passport.com/business.
34 Module 11: Internet Access

Permissions
Topic Objective
To explain which permission ! WebPermissions
classes best suit which
application types. " Controls an application's right to request data from a URI or to serve
a URI to the Internet
Lead-in ! SocketPermissions
The WebPermissions and
" Controls an application's right to accept data on a local port or to
SocketPermissions contact applications
classes provide Internet
security for applications that ! Choose Permission Class Based on Application Use
use System.Net. " WebRequest and its descendents use WebPermissions
" Socket-level access uses SocketPermissions
! Both Classes Support Two Kinds of Permissions
" Accept – application can answer an incoming connection
" Connect – application can initiate a connection

*ILLEGAL FOR NON-TRAINER USE**

The WebPermissions and SocketPermissions classes provide Internet security
for applications that use System.Net. The WebPermissions class controls an
application’s right to request data from a URI or to serve a URI to the Internet.
The SocketPermissions class controls an application’s right to accept data on a
local port or to contact applications through a transport protocol at another
address that is based on the host, port number, and transport protocol.
You should choose the permission class on the basis of your application type.
Applications that use WebRequest and its descendents should use the
WebPermissions class to manage permissions. Applications that use
socket-level access should use the SocketPermissions class to manage
permissions.
WebPermissions and SocketPermissions define two permissions: accept and
connect. Accept grants the application the right to answer an incoming
connection from another party. Connect grants the application the right to
initiate a connection to another party.
For WebPermissions, accept means that an application can export a particular
URI anywhere on the Internet. Connect means that an application can access
that URI, whether it is remote or local.
For SocketPermissions, accept means that an application can accept incoming
connections on a local transport address. Connect means that an application can
connect to a remote, or potentially local, transport address.
Module 11: Internet Access 35

Best Practices
Topic Objective
To introduce best practices
! When Possible, Use WebRequest and WebResponse,
that will help students use
the System.Net classes Instead of Protocol-Specific Subclasses
more effectively. ! For Better Performance, Use Asynchronous Methods
Lead-in
The following ! Tune Performance by Adjusting the Number
recommendations will help of Connections
you use the classes that are
contained in System.Net " ConnectionLimit property in the ServicePoint instance
more effectively.
! When Possible, Use TcpClient or UdpClient, Instead of
Writing Directly to a Socket
! Use the CredentialCache Class If Credentials
Are Required

*ILLEGAL FOR NON-TRAINER USE**

The following recommendations will help you use the classes that are contained
in System.Net more effectively:
! Whenever possible, use WebRequest and WebResponse, instead of
typecasting to descendent classes.
Applications that use WebRequest and WebResponse can take advantage
of new Internet protocols without extensive code changes.
! When writing ASP.NET applications that run on a server that uses the
System.Net classes, it is often better, from a performance standpoint, to use
the asynchronous methods for GetResponse and GetResponseStream.
! Set the ConnectionLimit property in the ServicePoint instance for your
application.
The number of connections opened to an Internet resource can have a
significant effect on network performance and throughput. By default,
System.Net uses two connections per application for each host. Setting the
ConnectionLimit property in the ServicePoint instance for your
application can increase this number.
! When writing socket-level protocols, try to use the TcpClient or UdpClient
classes, instead of writing directly to a socket.
The TcpClient and UdpClient classes encapsulate the creation of TCP and
UDP sockets without requiring you to handle the details of the connection.
! When accessing sites that require credentials, use the CredentialCache
class to create a cache of credentials, rather than supplying them with every
request.
The CredentialCache class will search the cache to find the appropriate
credential to present with a request, thus relieving you of the responsibility
of creating and presenting credentials based on the URI.
36 Module 11: Internet Access

Lab 11: Creating a DateTime Client/Server Application

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will create a
client application that uses
the System.Net.Sockets
.TcpClient class to connect
to and obtain date and time
information from a server.
You will also create a server
application that uses the
System.Net.Sockets
.TcpListener class to
accept requests from and
provide date and time
information to clients.

*ILLEGAL FOR NON-TRAINER USE**

Objectives
After completing this lab, you will be able to:
! Create a client application that uses the System.Net.Sockets.TcpClient
class to connect to and obtain date and time information from a server.
! Create a server application that uses the System.Net.Sockets.TcpListener
class to accept requests from and provide date and time information to
clients.

Lab Setup
Only solution files are associated with this lab. The solution files for this lab are
in the folder <install folder>\Labs\Lab11\Solution.

Scenario
In this lab, you will create two Microsoft Visual Studio® .NET console
applications: DateTimeClient and DateTimeServer. The DateTimeClient
application will make a TCP connection to the DateTimeServer application and
obtain a stream that contains date and time information. The DateTimeClient
will read the stream and convert the stream’s ASCII data into a string that is
then output to the console.

Estimated time to complete this lab: 45 minutes

Module 11: Internet Access 37

Exercise 1
Creating the DateTime Server
In this exercise, you will create a server application that will provide date and
time information to clients through TCP.

! Create the server application

1. In Visual Studio .NET, create a new C# console application project named
DateTimeServer in <install folder>\Labs\Lab11.
2. Rename the starting C# source file Datetimeserver.cs.
3. Add the following using statements:
using System.Net;
using System.Net.Sockets;
using System.Text;

4. Rename the wizard generated Class1 to Server.

5. Modify the Main method in the following steps.
6. In the try section of a try/catch block:
a. Instantiate a TcpListener object to listen on port 14.
b. Start the TcpListener object.
c. Write out the following message to the console:
Waiting for clients to connect
Press Ctrl+c to Quit...

d. Enter an infinite loop that will:

i. Accept TCP client connections using the AcceptSocket method.
ii. Call a DateTime method to get the current date and time.
iii. Create a string that consists of the short version of the date, followed
by the long version of the time.
iv. Convert the string to an ASCII-encoded byte array.
v. Send this byte array to the TCP client.
vi. Close the socket.
vii. Write out to the console a message that contains the string that was
just sent.
7. In the catch section of the try/catch block:
• Catch any exceptions of type SocketException and if the exception’s
ErrorCode property has a value of 10048, then write to the console a
message that states “Connection to this port failed. There is another
server is listening on this port.”
8. Build the server application.
38 Module 11: Internet Access

Exercise 2
Creating the DateTime Client
In this exercise, you will create a client application. The client application takes
as its runtime argument the name of the computer on which the server is
running. The client connects to the server to obtain date and time information
through TCP. The client then displays the date and time information on the
console.

! Create the client application

1. In Visual Studio .NET, create a new C# console application project named
DateTimeClient in <install folder>\Labs\Lab11.
2. Rename the starting C# source file Datetimeclient.cs.
3. Add the following using statements:
using System.Net;
using System.Net.Sockets;
using System.IO;
using System.Text;

4. Rename the wizard generated Class1 to Client.

5. Make the static Main method capable of handling runtime-supplied
arguments.
6. In the Main method, add code to:
a. Create a TcpClient object.
b. Create a byte array object of size 32 bytes.
c. Check the number of runtime arguments. If the number of arguments is
not one, print out an error message to the console, and exit. The message
should state:
Please specify a server name in the command line

d. In a try/catch block, verify that the named server computer exists by

calling the GetHostByName method of the Dns class. Catch any
SocketException exceptions and write out to a console window the
message “Cannot find server: ”, followed by the name of the server and
the exception’s data. Then exit the application.
e. Connect to the named server using port 14.
f. Declare a variable of type Stream.
g. In a try/catch block, get the stream and assign it to the variable declared
in the preceding step. Catch any InvalidOperationException
exceptions and write out to a console window the message “Cannot
connect to server ”, followed by the server’s name, and then exit the
application.
h. Read all of the bytes in the stream into the byte array that you created in
step 6b, and store the number of bytes that are read in an integer.
i. Convert the ASCII-encoded byte array into a string.
j. Write out to a console window a message that states the number of bytes
received and the current date and time string retrieved from the server.
Module 11: Internet Access 39

k. Close the TcpClient object.

l. Write out to a console window the following message:
Press Enter to exit.
m. Do a read from the console to wait for the Enter key and exit the
application.
7. Build the client application.

! Test the client and server applications

1. Ensure that there are no server applications running on the computer using
port 14, for example, other instances of the server application.

Tip You can display your computer’s current TCP/IP network connections
by running the program netstat in a command prompt window. The
following example shows that port 7 is in use by a process with PID 1504:
C:\>netstat -o -n -a

Active Connections

Proto Local Address Foreign Address State PID

TCP 0.0.0.0:7 0.0.0.0:0 LISTENING 1504 …

2. Run the server application in a Visual Studio .NET Command Prompt

window or in the Visual Studio .NET debugger.
3. Run the client application in another Visual Studio .NET Command Prompt
window or in another Visual Studio .NET debugger. Do not specify any
runtime arguments.
4. Note that the client application returns with the proper error message, as
follows:
Please specify a server name in the command line

5. Run the client application as directed in step 3 with a runtime argument that
contains a nonexistent server name. For example, assuming that there is no
computer named foo on the network, enter the following text in a
Visual Studio .NET Command Prompt window:
datetimeclient foo
40 Module 11: Internet Access

6. Note that the client application returns with the proper error message, for
example:
Cannot find server: foo
…

7. Run the client application as directed in step 3 with a runtime argument that
contains the name of the computer on which the Datetimeserver application
is running. If the server application is running on your current computer,
specify the local computer as follows:
datetimeclient localhost

Note that the client application outputs the number of bytes received and the
current date and time string retrieved from the server.
Module 11: Internet Access 41

Review
Topic Objective
To reinforce module
objectives by reviewing
key points. ! Internet Application Scenarios
Lead-in ! The WebRequest and WebResponse Model
The review questions cover
some of the key concepts ! Application Protocols
taught in the module.
! Handling Errors
! Security
! Best Practices

*ILLEGAL FOR NON-TRAINER USE**

1. Name the four parts of the following URI:
http://www.microsoft.com/default.htm?foo=bar
Scheme identifier http
Server identifier www.Microsoft.com
Path identifier /default.htm
Query String ?foo=bar

2. Write the line of code that creates a WebRequest to the URI in question 1.
WebRequest req = WebRequest.Create
("http://www.microsoft.com/default.htm?foo=bar");

3. Write the line of code that gets a WebResponse from the WebRequest in
question 2.
WebResponse resp = req.GetResponse();

4. Write the line of code that gets a Stream from the WebResponse in
question 3.
Stream respstrm = resp.GetResponseStream();
42 Module 11: Internet Access

5. Name the type of Web-specific exceptions that are thrown by the

GetResponse method.
WebException

6. State how a WebRequest can be made to use the Secure Socket Layer
(SSL) protocol.
URI begins with https.

7. Name at least three authentication methods that are supported by the .NET
Framework.
Basic
Digest
Negotiate
NTLM
Kerberos
Module 11: Internet Access 43

Course Evaluation
Topic Objective
To direct students to a Web
site to complete a course
evaluation.
Lead-in
Between now and the end of
the course, you can go to
the Web site listed on this
page to complete a course
evaluation.

*ILLEGAL FOR NON-TRAINER USE**

Your evaluation of this course will help Microsoft understand the quality of
your learning experience.
At a convenient time before the end of the course, please complete a course
evaluation, which is available at http://www.metricsthatmatter.com/survey/.
Microsoft will keep your evaluation strictly confidential and will use your
responses to improve your future learning experience.
THIS PAGE INTENTIONALLY LEFT BLANK
Module 12: Serialization

Contents

Overview 1
Serialization Scenarios 2
Serialization Attributes 4
Object Graph 5
Serialization Process 7
Serialization Example 9
Deserialization Example 10
Custom Serialization 12
Custom Serialization Example 14
Security Issues 17
Lab 12: Serialization 18
Review 27
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, place or event is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

 2001-2002 Microsoft Corporation. All rights reserved.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Module 12: Serialization iii

Instructor Notes
Presentation: After completing this module, students will be able to:
30 Minutes
• Write an application that serializes and deserializes an object graph by using
Lab: either a binary or Simple Object Access Protocol (SOAP) XML format.
45 Minutes

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach
this module.

Required Materials
To teach this module, you need the Microsoft® PowerPoint® file 2349B_12.ppt.

Preparation Tasks
To prepare for this module, you should:
! Read all of the materials for this module.
! Complete the lab.
iv Module 12: Serialization

Module Strategy
Use the following strategy to present this module:
! Serialization Scenarios
Discuss briefly how serialization is used in scenarios such as persisting in-
memory objects to disk and in remoting. Mention the Microsoft .NET
Framework’s support for serialization and deserialization as an introduction
to the rest of the module.
! Serialization Attributes
Explain how to mark a class with serialization attributes in C# by using the
Serializable attribute. Also cover the NonSerialized attribute.
! Object Graph
Use the diagram on the Object Graph slide to discuss the object graph
concept and the algorithm that is used to serialize or deserialize an object
graph.
! Serialization Process
Introduce the classes that are used in the serialization process.
! Serialization Example
Discuss the code example on the Serialization Example slide in which
default serialization is performed on a graph of objects, whose root is an
ArrayList, and the serialized stream is written to a FileStream in binary
format.
! Deserialization Example
Use the preceding serialization example to show how to create a clone of the
graph by deserializing it.
! Custom Serialization
Discuss when to use custom serialization and the implementation details of
using the ISerializable interface to perform custom serialization and
deserialization.
! Custom Serialization Example
Show how to provide custom serialization for a class named
ISerializableExample.
! Security Issues
Because the serialization engine handles both the public and private state of
the objects that are passed to it, emphasize that streams with private data
should be treated carefully, and that some form of encryption should be used
for sensitive data, before that data is transmitted over the wire or persisted to
disk.
Module 12: Serialization 1

Overview
Topic Objective
To provide an overview of ! Serialization Scenarios
the module topics and
objectives.
! Serialization Attributes
Lead-in ! Object Graph
In this module, you will learn
about serialization and learn ! Serialization Process
how to write an application
that serializes and ! Serialization Example
deserializes an object graph ! Deserialization Example
by using a binary or SOAP
XML format. ! Custom Serialization
! Custom Serialization Example
! Security Issues

*ILLEGAL FOR NON-TRAINER USE**

Serialization is the process of converting a graph of objects into a linear
sequence of bytes. That sequence of bytes can be sent elsewhere, for example,
to a remote computer, and be deserialized, thereby making a clone in the remote
memory of the original graph of objects.
After completing this module, you will be able to:
• Write an application that serializes and deserializes an object graph by using
either a binary or Simple Object Access Protocol (SOAP) XML format.
2 Module 12: Serialization

Serialization Scenarios
Topic Objective
To show how serialization is
used.
! Persistence
Lead-in
Serialization is used in some " Store and retrieve a graph of objects to and from a file
very common scenarios,
such as persisting a graph ! Remoting
of objects to disk or to
objects in another process. " Pass by value arguments that are transmitted between
processes

*ILLEGAL FOR NON-TRAINER USE**

Serialization is used in some very common scenarios, such as persisting a graph
of objects to disk or to objects in another process. The Microsoft® .NET
Framework provides support for serialization and deserialization.

Persistence
Consider a simple single-user desktop application, such as a two-dimensional
drafting package that is built by using object-oriented techniques. In such an
application, a drawing is composed of different kinds of graphical objects of
various types. The application represents the drawing as a graph of in-memory
objects. One object represents the root of the entire picture. For example, a
simple round table could be represented by a graph that consists of a root object
that is an instance of a circle class. This instance of the circle class has four
children that are each instances of a line class.
To save the entire drawing to a disk file so the drawing can be restored after
rebooting the computer, you could force each class to implement a serialize and
corresponding deserialize method. However, this approach is a potentially
burdensome task for the application programmer.

Serialization in the .NET Framework

The .NET Framework common language runtime reduces the amount of work
that is involved in serialization. At run time, the common language runtime
maintains metadata that allows serialization code to discover the types and
values of all fields and properties that make up any object. Using the common
language runtime, an application requires only a few lines of code to serialize a
object, such as the drawing described in the preceding paragraphs, and write it
to a file, or to deserialize such a file into an in-memory graph of objects.
Module 12: Serialization 3

Remoting
In distributed computing, objects in one process may need to communicate with
objects in another process. In the .NET Framework, the term remoting is
typically used to refer to the process in which an object invokes a method in
another object that is not in the same application domain. If the remote method
takes as one of its arguments an object that lies at the root of a graph of objects,
and if all of the objects in the graph are marked as remote-by-value, you must
serialize a copy of the object graph and pass the graph to the remote object. The
remote object must then deserialize the argument into an in-memory graph of
objects.
For more information about remoting, see Module 13, “Remoting and Web
Services,” in Course 2349B, Programming with the Microsoft .NET Framework
(Microsoft Visual C# .NET).
4 Module 12: Serialization

Serialization Attributes
Topic Objective
To explain how to mark a
class with serialization ! To Mark a Class, Use Serializable Attribute
attributes in C#.
Lead-in [Serializable]
[Serializable] public
public class
class MyClass
MyClass {}
{}
If you are writing a class,
you should be aware of
serialization. ! To Skip Specified Members, Use NonSerialized Attribute
[Serializable]
[Serializable] public
public class
class MyClass
MyClass {{
[NonSerialized]
[NonSerialized] int
int _cashSize;
_cashSize;
//...
//...
}}

! To Provide Custom Serialization, Implement

ISerializable

*ILLEGAL FOR NON-TRAINER USE**

If you are writing a class, you should be aware of serialization. The common
language runtime’s serialization services are built with the assumption that a
type is not serializable unless the type is specifically marked as serializable. In
the simplest case, all you need to do is mark a class as serializable because the
runtime metadata understands everything about each object’s layout in memory,
and its field and property definitions.
To mark a type as serializable in C#, you use the Serializable attribute, which
is a reserved custom attribute. All fields in classes with this attribute are
serialized, even private fields.
In the following example, MyClass is marked as serializable:
[Serializable] public class MyClass {}

For slightly more complex classes that have state that is invalid to serialize, the
runtime provides support for marking those fields and properties as transient.
For example, the following code uses the NonSerialized attribute to ensure that
the _cashSize member of MyClass is not serialized:
[Serializable] public class MyClass
{
[NonSerialized] int _cashSize;
//...
}

The small set of classes that need to participate in their own serialization and
deserialization can provide a custom implementation of the ISerializable
interface. For more information about custom serialization, see Custom
Serialization in this module.
Module 12: Serialization 5

Object Graph
Topic Objective
To define an object graph 33 Dog
and explain its function.
Lead-in
An object graph is a set of
objects that share a set of 44 Cat 77 Duck 11 Mouse
references to each other.

99 Horse 22 Duck

*ILLEGAL FOR NON-TRAINER USE**

An object graph is a set of objects with references to each other. Serialization
must provide a way to represent the links between the graph’s objects in the
serialized stream that is created in the serialization process.

Understanding Object Graphs

Serialization of an object graph must provide a way to represent the links
between the graph’s objects in the serialized stream that it creates. The value
that is held in the field of the in-memory object, which links to another object,
is essentially a 32-bit address. This address has meaning only in the owner
address space and may change during garbage collection. Therefore,
serialization must allocate a unique number to each object in the stream.
The illustration in the slide shows a graph of animal objects. Each object is
represented as a box with its identification number inside the box and its class
name to the right of the box.
You can represent the graph of objects that is shown in this illustration with a
serialized stream, as in the following example:
Dog, 3, ref4, ref7, ref1 || Cat, 4, ref9 || Duck, 7 || Mouse,
1, ref9, ref2 || Horse, 9, ref4 || Duck, 2

The order in which you stream out the objects does not matter, nor does it
matter what numbers you assign to the objects. What does matter is that no two
objects are assigned the same number. The object numbers are significant only
within a serialized stream. They are simply a way to represent the graph
topology and to allow you to reconstruct a copy of that graph, perhaps on
another computer.
6 Module 12: Serialization

Tracking Object References

An algorithm that visits objects one at a time clearly must keep track of which
objects it has already visited, for example, by using an internal list. Without due
care, the algorithm may incorrectly serialize or deserialize an object graph.
For example, in the object graph in the illustration, to avoid entering an infinite
loop, you must detect the cycle in the graph that occurs because of the mutual
references between Cat 4 and Horse 9. During serialization, you must note that
the Cat 4 that is linked to by Dog 3 is the same Cat 4 that is linked to by Horse
9 to ensure that deserialization will result in both Dog 3 and Horse 9 referring
to the same Cat 4 object and not to two different copies.
Module 12: Serialization 7

Serialization Process
Topic Objective ! Classes Used by the Default Serialization Process
To introduce the classes
that are used in the " ObjectIDGenerator – generates IDs for objects
serialization process.
Lead-in " ObjectManager – tracks objects as they are being
The process of serializing deserialized
an object graph involves
identifying the individual ! Examples of Classes Used with Serialized Streams
objects in the graph and the
" FileStream, MemoryStream, NetworkStream
relationships between them.
! Formatter Class
" Writes or reads data in a specified format to the output
or input streams
" Runtime provides BinaryFormatter and SoapFormatter

*ILLEGAL FOR NON-TRAINER USE**

The process of serializing an object graph involves identifying the individual
objects in the graph and the relationships between them.

Classes Used by the Default Serialization Process

To create and track object ID numbers, serialization uses several classes, as
follows:
! ObjectIDGenerator
The ObjectIDGenerator class generates IDs for objects. It keeps track of
objects that have already been seen, so when you ask for the ID of an object,
the ObjectIDGenerator knows whether to return the existing ID, or to
generate, and remember, a new ID.
! ObjectManager
The ObjectManager class keeps track of objects as they are being
deserialized. During deserialization, queries are made to the
ObjectManager to determine whether a reference to an object that is in the
serialized stream refers to an object that has already been deserialized or to
an object that has not yet been deserialized. A reference to an object that has
already been deserialized is called a backward reference. A reference to an
object that has not yet been serialized is called a forward reference.
8 Module 12: Serialization

Both the ObjectIDGenerator and ObjectManager classes are pluggable, so

you can build your own alternatives.

Note During deserialization, fields are returned in the order in which they are
returned from reflection. Reflection does not guarantee that it will follow
metadata ordering.

You can serialize to many different kinds of streams, for example, to a

FileStream, a MemoryStream, or a NetStream. The serialized stream’s
format is determined by the formatter object that you instantiate.
The .NET Framework runtime provides the following formatter classes:
! BinaryFormatter
The BinaryFormatter class is used for a compact binary representation.
! SoapFormatter
The SoapFormatter class is used for an XML representation.

Because formatters are pluggable, you can also build your own formatters.
Module 12: Serialization 9

Serialization Example
Topic Objective class
class SerializeExample{
SerializeExample{
To provide an example of
serialization of an object public
public static
static void
void Main(String[]
Main(String[] args)
args) {{
graph. //
// create
create the
the object
object graph
graph
ArrayList
ArrayList ll == new
new ArrayList();
ArrayList();
Lead-in
This code sample shows for
for (int x=0; x< 100;
(int x=0; x< 100; x++)
x++) {{
how to perform default l.Add (x);
l.Add (x);
serialization of a graph of }}
objects, whose root is an //
// create
create the
the filestream
filestream
ArrayList. FileStream
FileStream ss == File.Create("foo.bin");
File.Create("foo.bin");
//
// create
create the
the BinaryFormatter
BinaryFormatter
BinaryFormatter
BinaryFormatter bb == new
new BinaryFormatter();
BinaryFormatter();
//
// serialize the graph to
serialize the graph to the
the stream
stream
b.Serialize(s, l);
b.Serialize(s, l);
s.Close();
s.Close();
}}
}}

*ILLEGAL FOR NON-TRAINER USE**

The following code sample shows how to perform default serialization of a
graph of objects, whose root is an ArrayList. The serialized stream is written to
a FileStream in binary format.
using System;
using System.IO;
using System.Collections;
using System.Runtime.Serialization;
using System.Runtime.Serialization.Formatters.Binary;

class SerializeExample
{

public static void Main(String[] args)

{
// create the object graph
ArrayList l = new ArrayList();
for (int x=0; x< 100; x++)
{
l.Add (x);
}
// create the filestream
FileStream s = File.Create("foo.bin");
// create the BinaryFormatter
BinaryFormatter b = new BinaryFormatter();
// serialize the graph to the stream
b.Serialize(s, l);
s.Close();
}
}
10 Module 12: Serialization

Deserialization Example
Topic Objective
To show how to create a class
class DeSerialize
DeSerialize
clone of the graph by {{
deserializing it. public
public static
static void
void Main(String[]
Main(String[] args)
args)
{{
Lead-in //
The preceding Serialization // open
open the
the filestream
filestream
FileStream
FileStream ss == File.OpenRead("foo.bin");
File.OpenRead("foo.bin");
Example shows how to
perform default serialization //
of a graph of objects, whose // create
create the
the formatter
formatter
BinaryFormatter
BinaryFormatter bb == new
new BinaryFormatter();
BinaryFormatter();
root is an ArrayList, with a
//
// deserialize
deserialize
serialized stream that is
ArrayList
ArrayList pp == (ArrayList)
(ArrayList) b.Deserialize(s);
b.Deserialize(s);
written to a FileStream in
binary format. s.Close();
s.Close();
//
// print
print out
out the
the new
new object
object graph
graph
//
// see module text for PrintValues’
see module text for PrintValues’ code
code
PrintValues(p);
PrintValues(p);
}}

*ILLEGAL FOR NON-TRAINER USE**

The preceding Serialization Example shows how to perform default
serialization of a graph of objects, whose root is an ArrayList, with a serialized
stream that is written to a FileStream in binary format.
The following code sample shows how to create a clone of the graph by
deserializing it. The root of the clone graph is called p.
using System;
using System.IO;
using System.Collections;
using System.Runtime.Serialization;
using System.Runtime.Serialization.Formatters.Binary;

class DeSerialize
{

public static void Main(String[] args)

{
// open the filestream
FileStream s = File.OpenRead("foo.bin");

// create the formatter

BinaryFormatter b = new BinaryFormatter();
// deserialize
ArrayList p = (ArrayList) b.Deserialize(s);
s.Close();
// print out the new object graph
PrintValues(p);
}

(Code continued the following page.)

Module 12: Serialization 11

public static void PrintValues( IEnumerable myList )

{
System.Collections.IEnumerator myEnumerator =
myList.GetEnumerator();
while ( myEnumerator.MoveNext() )
Console.WriteLine( "{0}", myEnumerator.Current );
}

}
12 Module 12: Serialization

Custom Serialization
Topic Objective ! Customize Serialization by Implementing ISerializable:
To explain what is required
to implement ISerializable " When some of the data is not valid after deserialization
for performing custom
serialization. " When some of the data must be obtained by calculation
Lead-in ! ISerializable Requires:
This module has so far
discussed the default " GetObjectData method, called during serialization,
serialization process. which returns a PropertyBag of type SerializationInfo
However, you may also
want to customize the way " PropertyBag, which contains the type of the object
data from a given object is being serialized and the name/object pairs for the values
serialized. being serialized
" A constructor, called during deserialization, which uses
SerializationInfo to reconstitute the state of the object

*ILLEGAL FOR NON-TRAINER USE**

This module has so far discussed the default serialization process. However,
you may also want to customize the way that data from a given object is
serialized.
Custom serialization can be useful when some of the data that is associated with
an object is no longer valid after deserialization. You may want to use custom
serialization when working with pointers or hashcodes, or when you want to
create data through calculations or other means that allow you to reconstruct the
full state of the object during deserialization.
To perform custom serialization, you should implement the ISerializable
interface on the given object.

Implementation Details Required by ISerializable

To implement the ISerializable interface, you implement the GetObjectData
method on your object and add a constructor that takes a SerializationInfo and
a StreamingContext, as shown in Custom Serialization Example in this
module.
When GetObjectData is called during serialization, you are responsible for
populating a SerializationInfo object. A SerializationInfo object is a
PropertyBag that contains the type of the object that is being serialized and the
name/object pairs for the values that are being serialized.
The Formatter emits the data out onto the wire in the method required by its
particular format. You are free to serialize as few or as many fields as you want,
but the data that is transmitted must be sufficient to reconstitute the entire state
of the object. If the base object of the current class implements ISerializable, it
is usually correct to call the base object’s ISerializable.GetObjectData and
add any additional fields that are required for serializing the derived class to the
returned SerializationInfo.
Module 12: Serialization 13

Deserialization
Deserialization occurs during the call to the class’s constructor. If you need to
create custom deserialization of an object, you use the object’s
SerializationInfo, which has been populated with the type of the object and the
name/object pairs that were transmitted over the stream. You are responsible for
completely reconstituting the state of the object from this information. If the
base class also implements ISerializable, you are responsible for calling the
base class’s constructor. The serialization infrastructure will delay the call on
this constructor until the entire SerializationInfo has been completed.
If, for example, the SerializationInfo that is transmitted references objects A,
B, and C, the SerializationInfo that is passed to the constructor will have been
populated with references to objects A, B, and C. However, there is no
guarantee that any of the objects that are referenced by A, B, or C has been
completed.
Because there is no guarantee that any of the objects that are referenced by A,
B, or C have been completed, you cannot safely call any code on A, B, or C that
may require the objects to which they refer. For some objects, this code may
include code as simple as GetHashCode.
If your code requires you to perform any execution that is based on the value of
data that is contained in the objects that are referenced, it is usually best to
cache the SerializationInfo and then implement IDeserializationCallback.
14 Module 12: Serialization

Custom Serialization Example

[Serializable]
[Serializable] public
public class
class ExampleFoo
ExampleFoo :: ISerializable
ISerializable
Topic Objective {{
To provide an example of public
public int
int i,
i, j,
j, k;
k;
custom serialization. public
public ExampleFoo()
ExampleFoo() {} {}
internal
internal ExampleFoo(SerializationInfo
ExampleFoo(SerializationInfo si, si,
Lead-in StreamingContext
StreamingContext context)
context) {{
This example shows how to //Restore
//Restore ourour scalar
scalar values.
values.
provide custom serialization ii == si.GetInt32("i");
si.GetInt32("i");
jj == si.GetInt32("j");
si.GetInt32("j");
for a class named kk == si.GetInt32("k");
si.GetInt32("k");
ISerializableExample. }}
public
public void
void GetObjectData(SerializationInfo
GetObjectData(SerializationInfo si, si,
StreamingContext
StreamingContext context)
context) {{
//SerializationInfo
//SerializationInfo -- essentially
essentially aa property
property bag
bag
//Add
//Add our
our three
three scalar
scalar values;
values;
si.AddValue("i",
si.AddValue("i", i); i);
si.AddValue("j",
si.AddValue("j", j); j);
si.AddValue("k",
si.AddValue("k", k); k);
Type
Type tt == this.GetType();
this.GetType();
si.AddValue("TypeObj",
si.AddValue("TypeObj", t); t);
}}
}}

*ILLEGAL FOR NON-TRAINER USE**

The following example shows how to provide custom serialization for a class:
using System;
using System.IO;
using System.Runtime.Serialization;
using System.Runtime.Serialization.Formatters;
using System.Runtime.Serialization.Formatters.Soap;

public class Sample

{
public static void Main()
{
ToFile();
FromFile();
}

(Code continued the following page.)

Module 12: Serialization 15

public static void ToFile()

{
Console.WriteLine("ToFile");
ExampleFoo fooOut = new ExampleFoo();
fooOut.i = 1;
fooOut.j = 20;
fooOut.k = 50;

Console.WriteLine("i: {0}", fooOut.i);

Console.WriteLine("j: {0}", fooOut.j);
Console.WriteLine("k: {0}", fooOut.k);

IFormatter objFormatterToStream = new SoapFormatter();

Stream toStream = new FileStream("myFoo.xml",
FileMode.Create, FileAccess.Write, FileShare.None);
objFormatterToStream.Serialize(toStream, fooOut);
toStream.Close();
}

public static void FromFile()

{
Console.WriteLine("FromFile");
//Then you can read it back in with code like this:
IFormatter objFormatterFromStream = new SoapFormatter();
Stream fromStream = new FileStream("myFoo.xml",
FileMode.Open, FileAccess.Read, FileShare.Read);
ExampleFoo fooIn = (ExampleFoo)
objFormatterFromStream.Deserialize(fromStream);
fromStream.Close();

Console.WriteLine("i: {0}", fooIn.i);

Console.WriteLine("j: {0}", fooIn.j);
Console.WriteLine("k: {0}", fooIn.k);
}
}

[Serializable]
public class ExampleFoo : ISerializable
{
public int i, j, k;

public ExampleFoo()
{
}

internal ExampleFoo(SerializationInfo si,

StreamingContext context)
{
//Restore our scalar values.
i = si.GetInt32("i");
j = si.GetInt32("j");
k = si.GetInt32("k");
}

(Code continued on the following page.)

16 Module 12: Serialization

public void GetObjectData(SerializationInfo si,

StreamingContext context)
{
//SerializationInfo is essentially a property bag.

//Add our three scalar values;

si.AddValue("i", i);
si.AddValue("j", j);
si.AddValue("k", k);

Type t = this.GetType();
si.AddValue("TypeObj", t);
}
}

Outputs:
ToFile
i: 1
j: 20
k: 50
FromFile
i: 1
j: 20
k: 50
Module 12: Serialization 17

Security Issues
Topic Objective
To alert students to the
need for security when
serializing objects. ! Serialization Handles an Object’s Private Data
Lead-in " If private data is sensitive, consider encrypting the
The serialization engine stream before transmitting or saving to a disk
handles both the public and
private state of the objects " System.Security.Cryptography namespace contains
that are passed to it. classes to perform cryptography
The CryptoStream class can be used to encrypt
streams of serialized data

*ILLEGAL FOR NON-TRAINER USE**

The serialization engine handles both the public and private state of the objects
that are passed to it. When serializing an object to a stream, you must remember
that the stream now contains the public and private data of the object.
If the private data is sensitive, you should treat the stream with particular care.
For example, the stream should not be transmitted over the wire or persisted to
disk without some form of encryption.
18 Module 12: Serialization

Lab 12: Serialization

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will write a
client/server application that
uses serialization.

*ILLEGAL FOR NON-TRAINER USE**

Objectives
After completing this lab, you will be able to:
• Create an application that uses serialization as it is implemented by the
.NET Framework, to persist an object graph to and from a disk file in both
binary and SOAP XML format.

Lab Setup
Starter and solution files are associated with this lab. The starter files are in the
folder <install folder>\Labs\Lab12\Starter, and the solution files are in the
folder <install folder>\Labs\Lab12\Solution.

Scenario
In this lab, you will create a Microsoft Visual Studio® .NET console application
that uses the common language runtime’s ability to serialize an object graph in
memory to disk. You will create binary and SOAP formatter implementations
of the application.
In the first exercise, you will create a singly-linked linked list, which you will
fill with values and serialize to a file on disk. You will then deserialize the list
from the file on disk, thus restoring the list to an object graph in memory.
During deserialization, the elements within the list are swapped multiple times.
In the second exercise, you will modify the application to demonstrate the
ability of the .NET Framework’s serialization mechanism to handle object
graphs that contain multiple references to the same object and that contain
objects that have mutual references, which can create cycles in the graph.

Estimated time to complete this lab: 45 minutes

Module 12: Serialization 19

Exercise 1
Creating the Basic Serialization Application
In this exercise, you will modify the Serialization application to provide
methods to serialize and deserialize a linked list.

! To create the basic Serialization application in binary format

1. In the <install folder>\Labs\Lab12\Starter directory, open the Serialization
project in Visual Studio .NET and examine the Serialize.cs and
LinkedList.cs source files.
2. In Serialize.cs, locate the SaveListToDisk method, and add code to:
a. Create a Stream object that is initialized to a file named Linkedlist.bin
by using the static File.Create method.
b. Create a new BinaryFormatter object.
c. Invoke the method of the BinaryFormatter that serializes the
LinkedList parameter to the stream.
d. Close the file.
3. In Serialize.cs, locate the LoadListFromDisk method and add code to:
a. Create a Stream object that is initialized to a file named Linkedlist.bin
by using the static File.OpenRead method.
b. Create a new BinaryFormatter object.
c. Invoke the method of the BinaryFormatter that deserializes the stream
into a LinkedList named list2.
d. Close the file.
e. Output the contents of list2 to console by calling the LinkedList method
Draw().
f. Return list2.
4. Build the Serialization application.
20 Module 12: Serialization

5. Step through the application in the Visual Studio .NET debugger, and note
that due to the random swapping your output may vary slightly from the
following:
Entering Scope 1
Creating and filling List ..
List: 1 2 3 4 5 6 7 8 9
Serializing LinkedList to file ..
Leaving Scope 1

Entering Scope 2
Deserializing LinkedList from binary file ..
List: 1 2 3 4 5 6 7 8 9
Swapping Entries
Swapping 1 and 2
Swapping 3 and 4
Swapping 5 and 6
Swapping 7 and 8
List: 2 1 4 3 6 5 8 7 9
Serializing LinkedList to file ..
Leaving Scope 2

Entering Scope 3
Deserializing LinkedList from binary file ..
List: 2 1 4 3 6 5 8 7 9
Swapping Random Entries
Swapping 2 and 8
Swapping 4 and 3
Swapping 4 and 3
Swapping 6 and 5
Swapping 1 and 4
Swapping 1 and 8
Swapping 2 and 4
Swapping 3 and 5
Swapping 7 and 2
Swapping 5 and 4
Swapping 6 and 2
Swapping 9 and 5
Swapping 1 and 7
Swapping 7 and 8
Swapping 8 and 2
List: 2 1 7 4 3 8 9 6 5
Serializing LinkedList to file ..
Leaving Scope 3

Entering Scope 4
Deserializing LinkedList from binary file ..
List: 2 1 7 4 3 8 9 6 5
Removing Entries
Removing 1
Removing 2
Removing 3
List: 7 4 8 9 6 5
Serializing LinkedList to file ..
Leaving Scope 4
Module 12: Serialization 21

Note You can open a binary file using Visual Studio .NET by running
Microsoft Windows® Explorer, Explorer.exe, and navigating to the binary
file’s icon. Then either right-click on the icon and choose Open With
Microsoft Visual Studio .NET, or drag and drop the icon into a running
Visual Studio .NET application’s left-hand File View pane.

6. Using Visual Studio .NET, open and visually examine the contents of the
Linkedlist.bin file in the bin\Debug subdirectory, and note the serialized list
data’s format, structure, and size.

! To create the basic Serialization application in SOAP format

1. Add code to the SaveListToDisk and LoadListFromDisk methods to use
the SoapFormatter to write to and read the LinkedList parameter to and
from a file named Linkedlist.soap.
2. Build and execute the application, and confirm that the console output
remains correct.
3. Using Visual Studio .NET, open and visually examine the contents of the
Linkedlist.soap file in the bin\Debug subdirectory, and note the serialized
list data’s format and size. Compare this list data’s format, structure, and
size to the Linkedlist.bin list data’s format, structure, and size.
22 Module 12: Serialization

Exercise 2
Handling Complex Object Graphs
In this exercise, you will modify the Serialization application to create and
manipulate an object graph that has multiple references to the same object and
has reference cycles.

! To create the complex Serialization application in SOAP format

1. In Serialize.cs, locate the Ser class and add a static method named
SaveArrayToDisk that returns a void and that takes as its single argument
an array of type Node. Within SaveArrayToDisk, add code to:
a. Iterate through the array of nodes, and, for each node, print out the
array’s index, the node’s value, and the value of the Node object in the
node’s NextNode field.
b. Write out a message to the console that states that the application is
serializing the array to a file.
c. Create a stream object that is initialized with the file named Array.soap
by using the static File.Create method.
d. Create a SoapFormatter object.
e. Serialize the node array to the file.
f. Close the file.
2. In the Ser class, add a static method named LoadArrayFromDisk that
takes no arguments and returns an array of type Node. Within
LoadArrayFromDisk, add code to:
a. Write out a message to the console that states that the application is
deserializing an array from the file.
b. Create a stream object that is initialized with the file named Array.soap
by using the static File.OpenRead method.
c. Create a SoapFormatter object.
d. Using the SoapFormatter object, deserialize the stream into an array of
type Node.
e. Close the file.
f. Iterate through the array of nodes, and, for each node, print out the
array’s index, the node’s value, and the value of the Node object in the
node’s NextNode field.
g. Return the array of type Node.
Module 12: Serialization 23

3. In the Ser class add a static public method named Scope5 that takes no
arguments and returns void. Within Scope5, add code to:
a. Create two objects of type Node named n0 and n1 that are initialized to
values 0 and 1 respectively.
b. Write out a message to the console that states that the application is
entering Scope5 and creating a graph cycle.
c. Assign n1 to the NextNode field of n0.
d. Assign n0 to the NextNode field of n1.
e. Create an array of type Node that is initialized to contain references to
the three objects: n0, n1, and n0. Note that index 0 and 2 refer to the
same object.
f. Call the SaveArrayToDisk method and pass in the array of type Node.
g. Write out a message to the console that states that the application is
leaving Scope5.
4. In the Ser class, add a static public method named Scope6 that takes no
arguments and returns void. Within Scope6, add code to:
a. Write out a message to the console that states that the application is
entering Scope6 and creating a graph cycle.
b. Assign to a variable named nodes of type array of Node the array that is
returned by the LoadArrayFromDisk method. The array references the
objects: n0, n1, and n0 that were created in step 1. Note that index 0 and
2 refer to the same object.
c. Write out a message to the console that states that the value of n0 is
changing to 42 and that this change should result in a change in the value
in both locations in the array.
d. Assign the integer 42 to the Value field of nodes[0].
e. Write out a message to the console that states that the array’s structure
should be preserved during serialization and deserialization.
f. Call SaveArrayToDisk to persist nodes to the disk.
g. Assign to a variable named nodes2 of type array of Node the array that
is returned by the LoadArrayFromDisk method.
h. Write out a message to the console that states that the value of n0 is
being incremented.
i. Increment by 1 the value of the first element of nodes2.
j. Call SaveArrayToDisk, and pass nodes2.
k. Write out a message to the console that states that the application is
leaving Scope6.
5. In the Main method of Ser, and after the call to the Scope4 method, add
calls to Scope5 and Scope6.
6. Build the Serialization application.
7. Step through the application in the Visual Studio .NET debugger, and note
console output similar to the following output:
24 Module 12: Serialization

Entering Scope 1
Creating and filling List ..
List: 1 2 3 4 5 6 7 8 9
Serializing LinkedList to file ..
Leaving Scope 1

Entering Scope 2
Deserializing LinkedList from soap file ..
Deserializing LinkedList from binary file ..
List: 1 2 3 4 5 6 7 8 9
Swapping Entries
Swapping 1 and 2
Swapping 3 and 4
Swapping 5 and 6
Swapping 7 and 8
List: 2 1 4 3 6 5 8 7 9
Serializing LinkedList to file ..
Leaving Scope 2

Entering Scope 3
Deserializing LinkedList from soap file ..
Deserializing LinkedList from binary file ..
List: 2 1 4 3 6 5 8 7 9
Swapping Random Entries
Swapping 8 and 7
Swapping 7 and 5
Swapping 6 and 5
Swapping 2 and 1
Swapping 1 and 8
Swapping 4 and 2
Swapping 2 and 3
Swapping 3 and 5
Swapping 9 and 4
Swapping 9 and 4
Swapping 6 and 8
Swapping 2 and 4
Swapping 2 and 1
Swapping 9 and 7
Swapping 1 and 5
List: 6 5 1 4 3 9 8 2 7
Serializing LinkedList to file ..
Leaving Scope 3

Entering Scope 4
Deserializing LinkedList from soap file ..
Deserializing LinkedList from binary file ..
List: 6 5 1 4 3 9 8 2 7
Removing Entries
Removing 1
Removing 2
Removing 3
List: 6 5 4 9 8 7
Serializing LinkedList to file ..
Leaving Scope 4

(Code continued on the following page.)

Module 12: Serialization 25

Entering Scope 5
Creating a circular reference:
n0's NextNode is n1 and n1's NextNode is n0
Also adding in a third node, n2, that is another reference
to n0
Node 0 Value: 0 Value of NextNode Ref: 1

Node 1 Value: 1 Value of NextNode Ref: 0

Node 2 Value: 0 Value of NextNode Ref: 1

Serializing Array to file ..

Leaving Scope 5

Entering Scope 6
Deserializing Array from file ..
Node 0 Value: 0 Value of NextNode Ref: 1

Node 1 Value: 1 Value of NextNode Ref: 0

Node 2 Value: 0 Value of NextNode Ref: 1

changing value of node n0 to 42

should change value in both locations in array

array's structure should be preserved during

serialization and deserialization

Node 0 Value: 42 Value of NextNode Ref: 1

Node 1 Value: 1 Value of NextNode Ref: 42

Node 2 Value: 42 Value of NextNode Ref: 1

Serializing Array to file ..

Deserializing Array from file ..
Node 0 Value: 42 Value of NextNode Ref: 1

Node 1 Value: 1 Value of NextNode Ref: 42

Node 2 Value: 42 Value of NextNode Ref: 1

incrementing value of node n0

Node 0 Value: 43 Value of NextNode Ref: 1

Node 1 Value: 1 Value of NextNode Ref: 43

Node 2 Value: 43 Value of NextNode Ref: 1

Serializing Array to file ..

Leaving Scope 6
26 Module 12: Serialization

8. Using Visual Studio .NET, open and visually examine the Array.soap file in
the bin\Debug subdirectory, and note the serialized array data’s format,
structure, and size.
Module 12: Serialization 27

Review
Topic Objective
To reinforce module ! Serialization Scenarios
objectives by reviewing
key points. ! Serialization Attributes
Lead-in ! Object Graph
The review questions cover
some of the key concepts ! Serialization Process
taught in the module.
! Serialization Example
! Deserialization Example
! Custom Serialization
! Custom Serialization Example
! Security Issues

*ILLEGAL FOR NON-TRAINER USE**

1. Declare a serializable class named Foo with two integer fields F1 and F2 in
which F2 is transient and should not be serialized.
[Serializable] public class Foo {
int F1;
[NonSerialized] int F2;

2. Name and describe the two kinds of formatters that the .NET Framework
provides.
BinaryFormatter for a compact binary
SoapFormatter for XML representation

3. Describe what a class should do to provide custom serialization.

The class should inherit from the ISerializable interface, implement the
interface’s GetObjectData method, and provide a constructor that
takes SerializationInfo and StreamingContext parameters.

4. What kind of data that is not normally accessible by clients can be made
visible by serialization?
Private object state
THIS PAGE INTENTIONALLY LEFT BLANK
Module 13: Remoting
and XML Web Services

Contents
Overview 1
Remoting 2
Remoting Configuration Files 19
Demonstration: Remoting 22
Lab 13.1: Building an Order-Processing
Application by Using Remoted Servers 28
XML Web Services 36
Lab 13.2: Using an XML Web Service 48
Review 54
Course Evaluation 56
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, place or event is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

 2001-2002 Microsoft Corporation. All rights reserved.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Module 13: Remoting and XML Web Services iii

Instructor Notes
Presentation: After completing this module, students will be able to:
120 Minutes
! Write and configure distributed applications that use .NET Remoting.
Lab: ! Create an XML Web service by using Microsoft® Visual Studio® .NET and
105 Minutes
ASP.NET.
! Consume an XML Web service by using the Web Services Description
Language tool (Wsdl.exe).

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach
this module.

Required Materials
To teach this module, you need the Microsoft PowerPoint® file 2349B_13.ppt.

Preparation Tasks
To prepare for this module, you should:
! Read all of the materials for this module.
! Practice the demonstrations.
! Complete the lab.
iv Module 13: Remoting and XML Web Services

Demonstrations
This section provides demonstration procedures that will not fit in the margin
notes or are not appropriate for the student notes.

Remoting
In this demonstration, you will show students how a client application uses
.NET Remoting to make a method call on an object in a server application.
The code for this demonstration is contained in one project and is located in
<install folder>\Democode\Mod13\Demo13.1. In addition, the code for the
individual demonstration is provided in the student notes.

Using Visual Studio .NET to Create an XML Web Service

In this demonstration, you will show students how to use Visual Studio .NET to
create an XML Web service.
The code for this demonstration is contained in one project and is located in
<install folder>\Democode\Mod13\Demo13.2. In addition, the code for the
individual demonstration is provided in the student notes.
In both of the preceding demonstrations, use the debugger to step through the
code while you point out features.
Module 13: Remoting and XML Web Services v

Module Strategy
Use the following strategy to present this module:
! Remoting
Use the diagram on the Remoting Overview slide to introduce the services
that are provided by the Microsoft .NET Framework for use with remoting.
You will cover each of these services in more detail in the subsequent slides
in this section.
Explain how channels and formatters are used to transmit data. Discuss how
the .NET Framework supports server-side and client-side activation of
remote objects and describe the differences between server-side and client-
side activation.
Explain how to control the lifetime of client-activated remote objects by
using a leasing mechanism. Discuss how objects are marshaled in .NET
Remoting.
Explain how to register and activate a remote object from the server side
and the client side.
Conclude this section with a brief discussion of client compilation
techniques.
! Remote Configuration Files
Discuss the use of configuration files in remoting. Do not spend time on the
.NET Remoting configuration file format; instead refer students to the .NET
Framework Software Developer’s Guide (SDK) documentation.
Because the module is long, conclude this part of the lecture and instruct
students to do Lab 13.1.
! XML Web Services
Explain how to use Visual Studio .NET to implement an ASP.NET XML
Web service and how to access the XML Web service from a Web browser
and a client application. Use the Using Visual Studio .NET to Create an
XML Web Service demonstration to illustrate the concepts that are covered
in this section.
Introduce the XML Web service discovery process and the tools that are
available for discovery.
Module 13: Remoting and XML Web Services 1

Overview
Topic Objective
To provide an overview of
the module topics and
objectives.
! Remoting
Lead-in ! Remoting Configuration Files
In this module, you will learn
about distributed ! XML Web Services
applications that use .NET
Remoting.

*ILLEGAL FOR NON-TRAINER USE**

Microsoft® .NET Remoting provides a framework that allows objects to interact
across remoting boundaries, for example, across application domains
(AppDomain).
XML Web services is a term for communication that uses industry-standard
HTTP and Simple Object Access Protocol (SOAP) protocols. You can
implement XML Web services by using remoting and by using ASP.NET.
After completing this module, you will be able to:
! Write and configure distributed applications that use .NET Remoting.
! Create an XML Web service by using Microsoft Visual Studio® .NET and
ASP.NET.
! Consume an XML Web service by using the Web Services Description
Language tool (Wsdl.exe).
2 Module 13: Remoting and XML Web Services

" Remoting
Topic Objective
To provide an overview of
the topics covered in this ! Remoting Overview
section.
! Channels and Formatters
Lead-in
This section shows how ! Activation and Proxies
.NET Remoting supports
communication in various ! Lease-Based Lifetime
scenarios.
! Object Marshaling
! Server Side
! Client Side
! Client Compilation Techniques

*ILLEGAL FOR NON-TRAINER USE**

.NET Remoting supports communication in the following scenarios:
! Between objects in different application domains
! In different processes
! On different computers

The common language runtime remoting infrastructure provides a rich set of

classes that enable you to ignore most of the complexities of deploying and
managing remote objects. Even with applications that run under different
runtime environments, the process of calling methods on remote objects is
almost identical to the process of calling local methods.
Module 13: Remoting and XML Web Services 3

Remoting Overview
Topic Objective
To provide an overview of
.NET Remoting.
Lead-in
The .NET Framework Client AppDomain Server AppDomain
provides several services
that are used in remoting. Client Formatter Formatter
Object
Server
Object
Server Channel Channel
Proxy

Remoting Boundary

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework provides several services that are used in remoting:
! Communication channels that are responsible for transporting messages to
and from remote applications
! Formatters that encode and decode messages before they are transported by
the channel
! Proxies that forward remote method calls to the proper object
! Remote object activation and lifetime support

Note Because the .NET context mechanism is beyond the scope of this course,
this module does not cover remoting calls between contexts.
4 Module 13: Remoting and XML Web Services

Channels and Formatters

! Channels Transport Messages To and From Remote Objects
Topic Objective
To explain how channels ! Client Selects a Channel That Is Registered on the Server
and formatters are used to
transmit data. # Before calling a remote object, the client registers the channel
Channels are registered on a per application domain basis
Lead-in
# One computer cannot have multiple channels listening to same port
Channels are used to
transport messages to and ! .NET Provides Implementation of HTTP and TCP Channels
from remote objects.
Formatters are used to # HTTP Channel default: SOAP protocol to transport XML messages
encode and serialize data # TCP Channel default:TCP protocol to transport binary messages
into messages before
transmission over a Faster than HTTP SOAP Web Services but not as open
channel. ! Example: Programmatic Registration of TCP Channel on Port 8085
using
using System.Runtime.Remoting.Channels;
System.Runtime.Remoting.Channels;
using
using System.Runtime.Remoting.Channels.Tcp;
System.Runtime.Remoting.Channels.Tcp;
TcpChannel
TcpChannel chan
chan == new
new TcpChannel(8085);
TcpChannel(8085);
ChannelServices.RegisterChannel(chan);
ChannelServices.RegisterChannel(chan);
*****************************ILLEGAL FOR NON-TRAINER USE******************************
Channels are used to transport messages to and from remote objects. When a
client calls a method on a remote object, the parameters, as well as other details
that are related to the call, are transported through the channel to the remote
object. Any results from the call are returned back to the client in the same way.
Formatters are used to encode and serialize data into messages before they are
transmitted over a channel.

Channel Selection
Because a client can use any of the channels that are registered on the server to
communicate with a remote object, you can select the channels that best suit
your needs. You can also customize any existing channel or build new ones that
use different communication protocols.
Channel selection is subject to the following rules:
! Channels must be registered before objects are registered. At least one
channel must be registered with the remoting infrastructure before a remote
object can be called.
! Channels are registered on a per application domain basis.
A single process may contain multiple application domains. When a process
dies, all channels that it registers are automatically destroyed.
! It is not valid to register a channel that listens on the same port on which
another channel is currently listening.
Though channels are registered on a per application domain basis, different
application domains on one computer cannot register the same channel that
listens on the same port.
Module 13: Remoting and XML Web Services 5

Clients can communicate with a remote object by using any registered channel.
The remoting framework ensures that the remote object is connected to the
proper channel when a client attempts to connect to it. The client is responsible
for specifying a channel before it attempts to communicate with a remote
object.
To specify a channel, you can use a .NET Remoting configuration file, or you
can call the RegisterChannel method on the ChannelServices class.
The .NET Framework provides support for HTTP, TCP, and SMTP channels.
Because .NET Remoting channels are pluggable, you can write and plug in
additional channels with unique transport and encoding requirements.

Formatters Used to Encode and Decode Messages

Each channel provides a default formatter. However you can specify the
formatter that you wish to use.

Note A Uniform Resource Identifier (URI) is a compact representation of a

resource that is available to your application through the Internet. You may be
more familiar with the term URL, which stands for Uniform Resource Locator.
URLs form a subset of the more general URI naming scheme. A URL identifies
an Internet resource that has a Web page address.

HTTP Channel
By default, the HTTP channel uses the SOAP protocol to transport messages to
and from remote objects. All messages are passed through the SOAP formatter,
where the message is changed into XML and serialized, and the required SOAP
headers are added to the stream.
Alternatively, you can specify the binary formatter, which results in a binary
data stream. In either case, the data stream is then transported to the target
Uniform Resource Identifier by using the HTTP protocol. You can create
industry-standard XML Web services by using the HTTP channel with the
default SOAP formatter.

TCP Channel
By default, the TCP channel uses a binary formatter to serialize all messages to
a binary stream and transports the stream to the target Uniform Resource
Identifier by using the TCP protocol.
Alternatively, you can specify the SOAP formatter, which results in an XML
data stream. You can obtain better performance by using the TCP channel with
the default binary formatter than you can by using XML Web services.
6 Module 13: Remoting and XML Web Services

Code Example
The following code example shows how to programmatically register a TCP
Channel on port 8085 by using ChannelServices.RegisterChannel:
using System;
using System.Runtime.Remoting.Channels;
using System.Runtime.Remoting.Channels.Tcp;
//...
TcpChannel chan = new TcpChannel(8085);
ChannelServices.RegisterChannel(chan);
//...

Security Issues
If you have a choice between using the HttpChannel and the TcpChannel, it is
recommended that you use the HttpChannel and host your remote objects in
Internet Information Services (IIS), no matter what the user authentication and
authorization models are. IIS hosting provides support for wire-level protection
using Secure Sockets Layer (SSL) and authentication using Integrated
Windows Authentication (formerly NTLM authentication) or Kerberos. For
configuring SSL and authentication, see the IIS documentation.
The TcpChannel, as an implementation of the Transmission Control Protocol
(TCP), does not have default support for some of the robust authentication
standards that the HTTP standard does. Within a secured environment (one that
has wire-level protection such as IPSec), the high-speed TcpChannel can be
used, but it is not recommended over the Internet or a nonsecure intranet.
You can use cryptography to protect data from being viewed or modified and
thereby provide secure channels of communication over otherwise insecure
channels. The System.Security.Cryptography namespace contains a set of
classes that allow you to perform both symmetric and asymmetric
cryptography, create hashes, and provide random number generation.
Successful cryptography is the result of combining these tasks. See the .NET
SDK for documentation about the System.Security.Cryptography namespace.
Module 13: Remoting and XML Web Services 7

Activation and Proxies

Topic Objective
To show how the remoting
framework supports server- ! Before Using a Remote Object, the Client Must Activate It
side and client-side # By calling new, Activator.CreateInstance, or Activator.GetObject
activation of remote objects
and to describe the ! Activation Returns Proxy Used by Client to Access Remote Object
differences between server- # Proxy represents remote object in client’s AppDomain
side and client-side
# Proxy forwards client’s calls, and returns results and exceptions
activation.
! Server-Side Activation – Automatic Instantiation by Server
Lead-in
The remoting framework # Single call object handles only one request (stateless)
supports server-side and # Singleton object services multiple clients and requests (stateful)
client-side activation of
remote objects. ! Client-Side Activation – Instantiation by Explicit Client Call
# State maintained between method calls for specific client instance

*ILLEGAL FOR NON-TRAINER USE**

The remoting framework supports server-side and client-side activation of
remote objects.
Server-side activation means that when a client attempts to access the object,
the object is instantiated on the server automatically. Client-side activation, on
the other hand, means that the object is instantiated in response to a deliberate
activation request from a client.
You can select the best activation model to control the instantiation and lifetime
of a remote object.

Methods of Remote Object Activation

Before a client can use a remote object, the remote object must be activated,
and the client must obtain a proxy to access the remote object.
You can activate a remote object by calling new or by calling the following
methods of the Activator class:
! Activator.CreateInstance
Used to create an object instance
! Activator.GetObject
Generally used to connect to an object that is already running at a specified
Uniform Resource Identifier
8 Module 13: Remoting and XML Web Services

The Role of Proxies in Remote Object Interaction

When a client activates a remote object, the client obtains a proxy to the class
instance on the server. Any interaction with a remote object occurs by reference
through the proxy. The proxy object acts as a representative of the remote
object and ensures that all calls that are made on the proxy are forwarded to the
correct remote object instance. All methods that are called on the proxy are
automatically forwarded to the remote class, and any results are returned to the
client.
From the client’s perspective, this process is identical to the process of making
a local call. Any exceptions that are thrown by the remote object are
automatically returned to the client. Because those exceptions are returned to
the client, the client can use try/catch blocks around sections of code to trap
and handle exceptions.

Server-Side Activation
Server-side activation supports single call and singleton modes of activation.

Single Call Objects

A single call object services only one request. Single call objects are useful in
scenarios in which:
! The overhead of creating an object is not significant.
! Objects are configured in a load-balanced fashion.
! State information is usually not needed between calls.

Because single call objects cannot hold state information between method calls,
they are sometimes referred to as stateless objects.

Singleton Objects
A singleton object services multiple clients and multiple requests. Therefore, a
singleton object can store state information between client invocations.
Singleton objects are useful when you want to share data explicitly between
clients and method invocations, and when the overhead of creating and
maintaining objects is substantial.
Because singleton objects can maintain their state over a prolonged period of
time, they are sometimes referred to as stateful objects.
Module 13: Remoting and XML Web Services 9

Client-Side Activation
Client-activated objects are activated on a request from the client. This method
of activating server objects is similar to the classic COM coclass activation. The
activation process is as follows:
1. When the client requests a server object, an activation request message is
sent to the remote application.
2. The server then creates an instance of the requested class and returns an
ObjRef object to the client application that invoked it.
3. A proxy is then created on the client side by using the ObjRef object.

A client-activated object can store state information between method calls for
its specific client. However, state information is not shared between multiple
client-activated objects. Each request for a remote object instance returns a
proxy to an independent instance of the server type.
A useful function of client-activated objects is that constructor arguments can
be passed by the local application to the constructor of the object in the remote
application.
10 Module 13: Remoting and XML Web Services

Lease-Based Lifetime
Topic Objective
To explain how using a
leasing mechanism can
extend the lifetime of client- ! A Leasing Mechanism Controls the Lifetime of a Client-
activated remote objects. Activated Remote Object
Lead-in ! An Object’s Lease Time Can Be Extended
You can control the lifetime
of client-activated remote ! When an Object’s Lease Time Reaches Zero
objects by using a leasing
mechanism. # The object is disconnected from remoting infrastructure
# The object may be garbage-collected
# A lease provides an alternative to reference counting

*ILLEGAL FOR NON-TRAINER USE**

You can control the lifetime of client-activated remote objects by using a
leasing mechanism. When an object is first created, it is given a lease time.
When the lease time of the object reaches zero, the object is disconnected from
the remoting infrastructure. After the references to the object from within the
object’s application domain have been freed, the object may be collected when
the next garbage collection occurs.
You can extend the lease on an object by using a number of mechanisms. For
more information about extending the lease on an object, see “Lease-Based
Lifetime Concepts” in the .NET Framework Software Development Kit (SDK)
documentation.
You can use leases to manage the lifetime of remote objects as an alternative to
reference counting, which tends to be complex and inefficient over unreliable
network connections.
A potential disadvantage of leasing is that the lifetime of a remote object may
be extended for longer than is required. However, the advantages of reducing
network traffic that is devoted to reference counting and the pinging of clients
outweigh the disadvantage of the extended lifetimes of remote objects.
Module 13: Remoting and XML Web Services 11

Object Marshaling
Topic Objective
To explain how objects are
marshaled in .NET ! Objects Instantiated Remotely Are Returned by Reference and
Remoting. Accessed by the Client Through a Proxy

Lead-in ! Remote Call Parameters, Return Values, and Fields Can Be:
Because calls to a remote # Marshal-by-value objects – A copy of the object is passed from one
object can cause other AppDomain to another
objects to be passed across
- Value types and classes that are serializable
a remoting boundary, you
should understand how # Marshal-by-reference objects – A reference to the object is passed
objects are marshaled in from one AppDomain to another
.NET Remoting. - Classes that derive from the System.MarshalByRefObject class
# Not-marshaled objects – Objects suitable for local use only
- Any class that is not Marshal-By-Value or Marshal-By-Reference

*ILLEGAL FOR NON-TRAINER USE**

Because calls to a remote object can cause other objects to be passed across a
remoting boundary, you should understand how objects are marshaled in .NET
Remoting.
Inside the remoting boundary of the caller, for example, inside a single
application domain, objects are passed by reference, and primitive data types
are passed by value. Application domains are hard boundaries. Applications
running in different application domains share no information, no global
variables, and no static fields on classes. As mentioned in Remoting in this
module, .NET Remoting is used to communicate between objects in different
application domains.
All objects that are instantiated remotely are returned by reference. When a
client instantiates a remote object, it receives a proxy to the class instance on
the server. All methods that are called on the proxy are automatically forwarded
to the remote class, and any results are returned to the client.
The following examples show scenarios where objects are passed across
remoting boundaries because of calls to remote objects:
! Object parameters in a method call, such as myObj in:
public int myRemoteMethod (MyRemoteObject myObj)

! Object return values of method calls, such as MyRemoteObject instances

in:
public MyRemoteObject myRemoteMethod(String myString)

! Objects that result from property or field access of a remote object, such as
instances that are accessed in the myNestedObject field of myObj in:
myObj.myNestedObject

All objects in the .NET Framework fall into three general remoting categories:
marshal-by-value, marshal-by-reference, and not-marshaled.
12 Module 13: Remoting and XML Web Services

Marshal-By-Value Objects
Marshal-by-value objects include value types and classes that are serializable. A
copy of such marshal-by-value objects is passed from one application domain
to another.
You should use marshal-by-value objects when you need to move the complete
state of the object with the execution to the target application domain for
performance or processing purposes. In many scenarios, marshal-by-value
objects reduce boundary crossing, such as network, process, and application
domain roundtrips. Marshal-by-value objects have no distributed identity, and
no proxy is ever created to reference them, as shown in the following example:
[Serializable]
class Foo1A
{
//. . .
}

To participate in its own serialization when it is marshaled across application

domain boundaries, an object can expose the ISerializable interface, as in the
following example:
using System.Runtime.Serialization;
//...
[Serializable]
class Foo1B : ISerializable
{
//. . .
}

Marshal-By-Reference Objects
References to marshal-by-reference objects are made when the object reference
(ObjRef) is passed from one application to another. When the object reference
arrives in the remote application, it is converted to a proxy back to the original
object. The original object remains in the application domain in which it was
created. A marshal-by-reference object’s class must derive from the
System.MarshalByRefObject class.
Use marshal-by-reference objects when an object’s state should remain in the
application domain in which it was created and when only references to that
object should be marshaled at the time that the object is remoted. For example,
make a file object, whose internal representation contains a field that is an
operating system handle, application domain-bound. In this case, the operating
system handle would not be useful or appropriate in another application
domain, process, or computer.
All operations on a marshal-by-reference object are appropriately indirected so
that the common language runtime can intercept and forward them. This
indirection applies to fields, properties, and methods of marshal-by-reference
objects. For this reason, the performance overhead of marshal-by-reference
objects is greater than the performance overhead of marshal-by-value objects.
Module 13: Remoting and XML Web Services 13

The following example declares a class Foo2 that is marshal-by-reference:

class Foo2 : MarshalByRefObject
{
//. . .
}

Not-Marshaled Objects
Not-marshaled objects are the default for all objects that do not derive from
System.MarshalByRefObject and that do not have the [Serializable] custom
attribute. The use of not-marshaled objects is appropriate when an object should
not leave the application domain because the object was designed for local use
only, as in the following example:
class Foo3
{
//. . .
}
14 Module 13: Remoting and XML Web Services

Server Side
Topic Objective
To explain how to register
and activate a remote object ! Register the Channel
from the server side.
! Register Remote Objects by Using:
Lead-in
Remote objects must be # The RegisterWellKnownServiceType call
registered with the remoting
framework before clients RemotingConfiguration.RegisterWellKnownServiceType(
RemotingConfiguration.RegisterWellKnownServiceType(
can access them. typeof(HelloServer),
typeof(HelloServer),
"SayHello",
"SayHello",
WellKnownObjectMode.SingleCall);
WellKnownObjectMode.SingleCall);

# Or a configuration file
RemotingConfiguration.Configure("MyHello.exe.config");
RemotingConfiguration.Configure("MyHello.exe.config");

*ILLEGAL FOR NON-TRAINER USE**

All remote objects must be registered with the remoting framework before
clients can access them. Object registration is usually performed by a hosting
application that starts up, registers one or more channels with
ChannelServices, registers one or more remote objects with
RemotingServices, and then waits until it is terminated.

Note The registered channels and objects are available only while the process
that registered them is alive. When the process terminates, all channels and
objects that are registered by this process are automatically removed from the
remoting services where they were registered.

The following information is required when you register a remote object with
the remoting framework:
! The type name of the remote object
! The object Uniform Resource Identifier that clients will use to locate the
object
! For server-side activation, the object mode that is required
• The object mode can be single call or singleton.
Module 13: Remoting and XML Web Services 15

Methods of Remote Object Registration

You can register a remote object by calling
RemotingConfiguration.RegisterWellKnownServiceType, and passing the
information that is described in the preceding list as parameters, or by storing
that information in a configuration file and then calling
RemotingConfiguration.Configure and passing the name of the configuration
file as a parameter.
RegisterWellKnownServiceType and Configure perform the same function,
but Configure is more convenient to use because the contents of the
configuration file can be altered without recompiling the host application.

RegisterWellKnownServiceType
The following example code shows how to register the HelloServer class as a
SingleCall remote object by using the RegisterWellKnownServiceType
method.
RemotingConfiguration.RegisterWellKnownServiceType(
typeof(HelloServer),
"SayHello",
WellKnownObjectMode.SingleCall);

In the preceding example, RemotingSamples.HelloServer is the name of the

class, and SayHello is the object Uniform Resource Identifier.

Configuration File
The following example code shows how to register the HelloServer class as a
SingleCall remote object by using the Configure method:
RemotingConfiguration.Configure("MyHello.exe.config");

In the preceding example, the configuration file, MyHello.exe.config stores the

same registration information that is stored in the parameters of the preceding
RegisterWellKnownServiceType method.
The format of the .NET Remoting configuration file is described in Remoting
Configuration Files in this module.
When the remote object in the preceding example is registered, the remoting
framework creates an object reference and then extracts the required metadata
about the object from the assembly. The object’s required metadata, the
Uniform Resource Identifier, and the assembly name are then stored in the
object reference, which is filed in a remoting framework table that is used for
tracking registered remote objects.

Note The remote object itself is not instantiated by the registration process.
Instantiation occurs only when a client attempts to call a method on the object
or activates the object from the client side.
16 Module 13: Remoting and XML Web Services

Client Side
Topic Objective
To explain how to register
! Register the Channel
and activate a remote object
from the client side. ChannelServices.RegisterChannel(new
ChannelServices.RegisterChannel(new TcpChannel());
TcpChannel());
Lead-in
On the client side, a client ! Activate Remote Object by Using:
registers the channel and
activates the remote object. # Activator.GetObject

HelloServer
HelloServer obj
obj == (HelloServer)Activator.GetObject(
(HelloServer)Activator.GetObject(
typeof(RemotingSamples.HelloServer),
typeof(RemotingSamples.HelloServer),
"tcp://localhost:8085/SayHello");
"tcp://localhost:8085/SayHello");

# new and a configuration file

RemotingConfiguration.Configure("MyHello.exe.config");
RemotingConfiguration.Configure("MyHello.exe.config");
HelloServer
HelloServer obj
obj == new
new HelloServer();
HelloServer();
*****************************ILLEGAL FOR NON-TRAINER USE******************************
On the client side, a client registers the channel and activates the remote object.

Registering the Channel

A client must first register the channel by calling
ChannelServices.RegisterChannel. As previously mentioned in Server Side in
this module, the server must first have registered the selected channel.
The following code example shows how to register a TCP Channel:
ChannelServices.RegisterChannel(new TcpChannel());

Important You do not specify a port number when you register the client
channel.

Activating Remote Objects

After the client registers the channel, it can then activate the remote object by
using GetObject or the new operator. It is important to note that the object is
not instantiated when either of these calls is made. Actually, no network calls
are generated at all. The remoting framework obtains enough information from
the metadata to create the proxy without connecting to the remote object. A
network connection is only established when the client calls a method on the
proxy.
When the call arrives at the server, the remoting framework extracts the
Uniform Resource Identifier from the message, examines the remoting
framework tables to locate the reference for the object that matches the Uniform
Resource Identifier, and then instantiates the object if necessary, forwarding the
method call to the object. If the object is registered as SingleCall, it is
destroyed after the method call is completed. For each method that is called, a
new instance of the object is created.
Module 13: Remoting and XML Web Services 17

The only difference between GetObject and new is that GetObject allows you
to specify a Uniform Resource Identifier as a parameter, while new obtains the
Uniform Resource Identifier from the configuration file.
You can use CreateInstance or new for client-activated objects. Both
CreateInstance and new allow you to instantiate an object by using
constructors with parameters. The lifetime of client-activated objects is
controlled by the leasing service that is provided by the remoting framework.

Using Activator.GetObject
The following example code shows how to obtain a server-activated object by
using Activator.GetObject:
HelloServer obj = (HelloServer)Activator.GetObject(
typeof(RemotingSamples.HelloServer),
"tcp://localhost:8085/SayHello");

In the preceding example, "tcp://localhost:8085/SayHello" specifies

that a connection should be made to the remote object at the SayHello endpoint
by using TCP on port 8085.

Using the new Operator

To use the new operator, you must load a configuration file with the remote
object’s information. For example, for a file called MyHello.exe.config, you
load the configuration file as follows:
RemotingConfiguration.Configure("MyHello.exe.config");

After the configuration file has been loaded, the client can activate the object as
follows:
HelloServer obj = new HelloServer();
18 Module 13: Remoting and XML Web Services

Client Compilation Techniques

Topic Objective
To explain how type
information is provided to
the compiler. ! When the Client Is Compiled, the Compiler Needs Server
Class Data
Lead-in
When compiling the client ! Class Information Can Be Provided by:
code, the compiler requires
type information about the # A reference to the assembly where the class is stored
HelloServer class.
# Splitting the remote object into an implementation class
and an interface type
# Using Wsdl.exe to extract the required metadata directly
from the endpoint

*ILLEGAL FOR NON-TRAINER USE**

When compiling the client code, the compiler requires type information about
the HelloServer class. This type information is discussed in the preceding
topic.
You can provide type information in one of the following ways:
! Provide a reference to the assembly in which the HelloServer class is
stored.
Providing a reference is useful when the client and server components are
developed at the same site.
! Split the remote object into an implementation class and an interface type,
and use the interface as a reference when compiling the client.
Splitting the remote object into an implementation class and an interface
type is useful when the client and server components are not developed at
the same site. The interface or interfaces can be compiled to a DLL and
shipped to the client sites when necessary. According to COM guidelines,
you should avoid changing the published interface.
! Use the Web Services Description Language tool (Wsdl.exe) to extract the
required metadata directly from the endpoint.
The Web Services Description Language tool lets you connect to the
endpoint that is provided, extract the metadata, and generate source code
that can then be used to compile the client. The Web Services Description
Language tool is useful when client and server components are developed at
different sites and when no interface classes are available.
To use the Web Services Description Language tool, point the tool at a
remote Uniform Resource Identifier and generate the required metadata.

Note The Web Service Utility extracts only metadata and does not generate the
source for the remote object.
Module 13: Remoting and XML Web Services 19

Remoting Configuration Files

Topic Objective
To explain how to configure
objects with configuration ! Configure Method on RemotingConfiguration
files for use in remoting.
RemotingConfiguration.Configure(foo.exe.config);
RemotingConfiguration.Configure(foo.exe.config);
Lead-in
Programmatic registration is ! An Application Configuration File is an XML Document
a simple process, but it is
not practical for use in real- # Configuration files are case-sensitive
life situations where large
numbers of remote objects
# Can be specified on a machine or on an application level
must be managed on a Application level configuration takes priority over
corporate network. machine level configuration
# For more information see “Remoting Configuration File
Format” in the .NET Framework SDK documentation

*ILLEGAL FOR NON-TRAINER USE**

Programmatic registration is a simple process, but it is not practical for use in
real-life situations where large numbers of remote objects must be managed on
a corporate network. Remoting configuration solves this problem by using a
configuration file, a simple mechanism, to register an object.
To configure an object with a configuration file, call the Configure method on
RemotingConfiguration, as shown in the following example:
using System;
using System.IO;
using System.Runtime.Remoting;

public class MyHost

{
public static void Main(String[] args)
{
if (args.Length == 0)
{
// Perform a default configuration, throw an exception
// or display usage information to the user
}
else
{
RemotingConfiguration.Configure (args[0]);
}
// The program should pause here till the
// registered objects are no longer required
}
}
20 Module 13: Remoting and XML Web Services

The Configure method loads the configuration file into memory, parses the
contents, and calls the relevant methods to register the channels and objects that
are described in the file.
You can also use configuration files to store such settings as binding policy and
security. The name of the configuration file includes the full module name and
the extension, with .config appended to that extension. For example, the
configuration file name for Foo.exe is Foo.exe.config.
Although .NET Remoting does not mandate how you name a configuration file,
you should use the naming convention that is described in the preceding
paragraph to ensure that specific security and binding policies are picked up
when an application is executed.
The Configure call on RemotingConfiguration only reads the relevant
sections in the configuration file that apply to remoting, while the rest of the
information is ignored.
Module 13: Remoting and XML Web Services 21

An application configuration file is an XML document that contains sections

for various feature areas. The general format is a follows:

Note Configuration files are case-sensitive.

All configuration information can be specified on a machine or on an

application level. Application level configuration takes priority over machine
level configuration.
For more information about the .NET Remoting configuration file format, see
“Remoting Configuration File Format” in the .NET Framework SDK
documentation.
22 Module 13: Remoting and XML Web Services

Demonstration: Remoting
Topic Objective
To demonstrate how a client
application uses .NET
Remoting to make a method
call on an object in a server
application.
Lead-in
This demonstration shows
how a client application
uses .NET Remoting to
make a method call on an
object in a server
application.

*ILLEGAL FOR NON-TRAINER USE**

This demonstration shows how a client application can use .NET Remoting to
make a method call on an object in a server application.

Delivery Tip Important Before running the application, ensure that all currently running
Although this demonstration server applications that may be using the same port number have been closed.
includes detailed Running more than one server that uses the same port number will generate an
instructions, this is not a error.
guided practice. Present the
demonstration and suggest
that the students try the
demonstration for Tip You can display your machine’s current TCP/IP network connections by
themselves later. running the program netstat in a command prompt window. The following
example shows that port 7 is in use by a process with PID 1504:
C:\>netstat -o -n -a

Active Connections

Proto Local Address Foreign Address State PID

TCP 0.0.0.0:7 0.0.0.0:0 LISTENING 1504 …
Module 13: Remoting and XML Web Services 23

Server-Side
The following sample code is the server source code, which is named Server.cs:
using System;
using System.Runtime.Remoting;
using System.Runtime.Remoting.Channels;
using System.Runtime.Remoting.Channels.Tcp;
using System.Runtime.Remoting.Channels.Http;

namespace RemotingSamples
{

public class HelloServer : MarshalByRefObject

{

public int callCounter = 0;

public static int Main(string [] args)

{

TcpChannel chan1 = new TcpChannel(8085);

HttpChannel chan2 = new HttpChannel(8086);

ChannelServices.RegisterChannel(chan1);
ChannelServices.RegisterChannel(chan2);

/*
RemotingConfiguration.RegisterWellKnownServiceType
(
typeof(HelloServer),
"SayHello",
WellKnownObjectMode.Singleton
);
*/

RemotingConfiguration.RegisterWellKnownServiceType(
typeof(HelloServer),
"SayHello",
WellKnownObjectMode.SingleCall
);

System.Console.WriteLine("Press Enter key to exit");

System.Console.ReadLine();
return 0;
}

(Code continued on the following page.)

24 Module 13: Remoting and XML Web Services

public HelloServer()
{
Console.WriteLine("HelloServer activated");
}

public String HelloMethod(String name,

out int counter)
{
counter = ++callCounter;
Console.WriteLine(
"Server Hello.HelloMethod : {0} Counter :{1}",
name, callCounter);
return "Hi there " + name;
}
}
}

The RemotingSamples.HelloServer class is derived from

MarshalByRefObject, so HelloServer is remotable. When the server is
started, you create and register a TCP channel that listens for clients to connect
on port 8085 and an HTTP channel that listens for clients to connect on port
8086. You also register the remote object with the remoting framework by
calling RegisterWellKnownServiceType.
The parameters for this call include the following:
! The full type of the object that is being registered, such as
RemotingSamples.HelloServer in the preceding example
! The name of the endpoint where the object will be published
To connect to the object, clients must know the name of the endpoint. Any
string can be used. In the preceding example, you use SayHello.
You can also connect to remote objects through ASP.NET. In the preceding
example, if you were connecting to remote objects through ASP.NET, the
endpoint would be RemotingSamples/HelloServer.soap.
! The object mode, which can be SingleCall or Singleton
In the preceding example, you initially specify SingleCall. The object mode
specifies the lifetime of the object when it is activated on the server. In the
case of SingleCall objects, a new instance of the class is created for each
call that is made from a client, even if the same client calls the same method
more than once.
Singleton objects, on the other hand, are created only once, and all clients
communicate with the same object.
Module 13: Remoting and XML Web Services 25

Client-Side
The following sample code is the client source code, which is named Client.cs:
using System;
using System.Runtime.Remoting;
using System.Runtime.Remoting.Channels;
using System.Runtime.Remoting.Channels.Tcp;
using System.Runtime.Remoting.Channels.Http;
using System.IO;

namespace RemotingSamples
{
public class Client
{
public static int Main(string [] args)
{
int counter;

TcpChannel chan1 = new TcpChannel();

ChannelServices.RegisterChannel(chan1);
HelloServer obj1 = (HelloServer)Activator.GetObject(
typeof(RemotingSamples.HelloServer),
"tcp://localhost:8085/SayHello");
if (obj1 == null)
{
System.Console.WriteLine(
"Could not locate TCP server");
return 1;
}

HttpChannel chan2 = new HttpChannel();

ChannelServices.RegisterChannel(chan2);
HelloServer obj2 =(HelloServer)Activator.GetObject(
typeof(RemotingSamples.HelloServer),
"http://localhost:8086/SayHello");
if (obj2 == null)
{
System.Console.WriteLine(
"Could not locate HTTP server");
return 1;
}

(Code continued on the following page.)

26 Module 13: Remoting and XML Web Services

try
{
Console.WriteLine(
"Client1 TCP HelloMethod {0} Counter {1}",
obj1.HelloMethod("Caveman", out counter),
counter);
Console.WriteLine(
"Client2 HTTP HelloMethod {0} Counter {1}",
obj2.HelloMethod("Caveman", out counter),
counter);
}
catch (IOException ioExcep)
{
Console.WriteLine("Remote IO Error" +
"\nException:\n" + ioExcep.ToString());
return 1;
}
return 0;
}
}
}

When the client starts up, it registers a TCP channel and an HTTP channel and
proceeds to activate an object on each channel by calling the GetObject
method on the Activator class.
The parameters for this call are the type of the name of the class that you need
to activate, RemotingSamples.HelloServer, and the endpoint Uniform
Resource Identifier.
For the client’s TCP connection, the Uniform Resource Identifier is
tcp://localhost:8085/SayHello.
For the client’s HTTP connection, the Uniform Resource Identifier is
http://localhost:8086/SayHello.

Important The Uniform Resource Identifier includes the protocol, computer

name, and port number, as well as the endpoint. If the server is deployed on a
host that is named Sunshine, clients can connect to the server that is using TCP
by specifying tcp://sunshine:8085/SayHello.

When you run the client, it locates and connects to the server, retrieves a proxy
for the remote objects, and calls the HelloMethod on the remote objects,
passing the string Caveman as a parameter and the counter as an out parameter.
The server returns Hi there Caveman and the count of the number of times that
the server object’s method has been called.
Module 13: Remoting and XML Web Services 27

Building and Executing the Server and Client

To build the server and the client in the same directory, type the following
command at the Microsoft Visual Studio .NET Command Prompt command
prompt:

Important To use Microsoft Visual Studio .NET tools within a command

prompt window, the command prompt window must have the proper
environment settings. The Visual Studio .NET Command Prompt window
provides such an environment. To run a Visual Studio .NET Command Prompt
window: on the Start menu point to All Programs, point to Microsoft
Visual Studio .NET, Visual Studio .NET Tools, and then click Visual Studio
.NET Command Prompt.

csc server.cs
csc /r:server.exe client.cs

To execute the application, start the server application from a console window,
and then start the client application from another console window.

Note The counter values on the two client calls should have the same value
because the server object’s activation mode is SingleCall.

Changing the Activation Mode

To change the server’s activation mode from SingleCall to Singleton, change
the RegisterWellKnownServiceType call in the server as follows:
RemotingConfiguration.RegisterWellKnownServiceType(
typeof(HelloServer),
"SayHello",
WellKnownObjectMode.Singleton);

Rebuild and execute as in the preceding example. Note the counter values on
both calls. They should increase after each call.
28 Module 13: Remoting and XML Web Services

Lab 13.1: Building an Order-Processing Application by

Using Remoted Servers
Topic Objective
To introduce the lab.
Lead-in
In this lab, you will create an
XML Web service hosted in
a .NET executable file,
create a TCP server, and
create a client that uses
.NET Remoting to access
an XML Web service and a
TCP server.

*ILLEGAL FOR NON-TRAINER USE**

Objectives
After completing this lab, you will be able to:
! Create an XML Web service hosted in a .NET executable file.
! Create a TCP server.
! Create a client that uses .NET Remoting to access both an XML Web
service and a TCP server.

Lab Setup
Only solution files are associated with this lab. The solution files for this lab are
in the folder <install folder>\Labs\Lab13.1\Solution.
Module 13: Remoting and XML Web Services 29

Scenario
This lab is based on a scenario of a simple distributed order-processing
application, in which a customer specifies a customer ID and an item number
for an item that the customer wants to purchase, and the application processes
the order. The order processing involves authenticating the customer’s ID and
arranging order fulfillment that is to say, having the ordered item sent to the
customer.
In this lab, you will create a distributed solution that uses .NET Remoting. You
will use .NET Remoting support of SOAP over HTTP to create a server
application that exports an authenticate method as an open standards-based
XML Web service. You will also use .NET Remoting support of TCP with
binary formatting to create a remote order fulfillment server application that
trades off the advantages of the open standards-based flexible XML Web
services protocol for improved performance.
In addition, you will create a simple test client to exercise these servers.
Because the focus of this lab is on .NET Remoting, the functionality that is
specific to authentication and fulfillment will be minimal.

Estimated time to complete this lab: 50 minutes

30 Module 13: Remoting and XML Web Services

Exercise 1
Creating an Authentication XML Web Service
In this exercise, you will create an XML Web service that provides simple
authentication. Simple authentication will consist of using a random-number
generator to authenticate the user successfully 50 percent of the time.

! Create the authentication server

1. Using the editor of your choice, create a C# source file named
Authenticate.cs, and save it in the Lab13.1 directory.
2. To simplify coding, add using statements to import the namespaces System,
System.Runtime.Remoting, System.Runtime.Remoting.Channels, and
System.Runtime.Remoting.Channels.Http.
3. Specify the namespace Lab13, and in it, create a public class named
AServer that is marshal-by-reference.
4. Add a field named aRandom to hold a reference to a random number
generator object of class System.Random.
5. In the Main method of AServer:
a. Create and register a channel that supports the protocol and format for an
XML Web service. Specify port 8086.
b. Invoke the RemotingConfiguration.RegisterWellKnownServiceType
method to register the authentication server whose full type name is
Lab13.AServer, and whose endpoint is DoAuthentication.
To retain the object’s state, that is to say, the random-number generator
object, over multiple client calls, the well-known object’s mode should
be stateful.
c. Print to the console a message that tells the user to press any key so the
server exits.
The program should wait for this user action before continuing.
6. Add a public default constructor that creates a new instance of the Random
class, assigns it to the field that was created in step 4, and prints a message
to the console that states that AServer is running.
Module 13: Remoting and XML Web Services 31

7. Add a public method named Authenticate that takes a customer ID of type

int and returns a bool value.
a. Assign to a variable named aRandomNumber of type double a random
number that is greater than or equal to 0 and is less than 1, by using the
following code:
double aRandomNumber = aRandom.NextDouble();

b. Using the value from step a, assign to a variable of type bool named
passed the value true for 50 percent of the time and the value false for
50 percent of the time.
c. Print to the console a message that identifies the customer and states
whether the customer is authenticated on the basis of the value of
passed.
d. Return passed.
8. In a Visual Studio .NET Command Prompt window, build Authenticate.exe.

Important To use Microsoft Visual Studio .NET tools within a command

prompt window, the command prompt window must have the proper
environment settings. The Visual Studio .NET Command Prompt window
provides such an environment. To run a Visual Studio .NET Command
Prompt window: on the Start menu point to All Programs, point to
Microsoft Visual Studio .NET, Visual Studio .NET Tools, and then click
Visual Studio .NET Command Prompt.
32 Module 13: Remoting and XML Web Services

Exercise 2
Creating a Fulfillment Server
In this exercise, you will create a server that provides simple order fulfillment
functionality by using TCP and a binary format to provide fast communication.
Simple fulfillment will consist of using a random-number generator to
successfully fulfill the order 50 percent of the time.

! Create the fulfillment server

1. Using the editor of your choice, create a C# source file that is named
Fulfillment.cs, and save it in the Lab13.1 directory.
2. To simplify coding, add using statements to import the namespaces System,
System.Runtime.Remoting, System.Runtime.Remoting.Channels, and
System.Runtime.Remoting.Channels.Tcp.
3. Specify the namespace Lab13, and in it, create a public class named
FServer that is marshal-by-reference.
4. Add a field named aRandom to hold a reference to a random-number
generator object of class System.Random.
5. In the Main method of FServer:
a. Create and register a channel that uses the TCP protocol and binary
formatting. Specify port 8085.

Note You cannot have two channels on one computer that are using the
same port number; therefore you cannot use port 8086.

b. Invoke the RemotingConfiguration.RegisterWellKnownServiceType

method to register the fulfillment server whose full type name is
Lab13.FServer, and whose endpoint is DoFulfillment.
To retain the object’s state, that is to say, the random-number generator
object, over multiple client calls, the well-known object’s mode should
be stateful.
c. Print to the console a message that tells the user to press any key so the
server exits.
The program should wait for this user action before continuing.
6. Add a public default constructor that creates a new instance of the Random
class, assigns it to the field that was created in step 4, and prints a message
to the console that states that FServer is running.
Module 13: Remoting and XML Web Services 33

7. Add a public method named Fulfill that takes a customer ID of type int, an
item number of type int, and returns a bool value.
a. Assign to a variable named aRandomNumber of type double a random
number that is greater than or equal to 0 and less than 1, by using the
following code:
double aRandomNumber = aRandom.NextDouble();

b. Using the value from step a, assign to a variable of type bool named
shipped the value true for 50 percent of the time and the value false for
50 percent of the time.
c. Print to the console a message that identifies the customer and the item
number and states whether the item was shipped on the basis of the
value of shipped.
d. Return shipped.
8. In a Visual Studio .NET Command Prompt window, build Fulfillment.exe.
34 Module 13: Remoting and XML Web Services

Exercise 3
Creating a Test Client
In this exercise, you will create a test client application to test the order-
processing servers. The client calls the authentication XML Web service. If the
user is authenticated, the client calls the order fulfillment server.

! Create the test client

1. Using the editor of your choice , create a C# source file named Testclient.cs,
and save it in the Lab13.1 directory.
2. To simplify coding, add using statements to import the namespaces System,
System.Runtime.Remoting, System.Runtime.Remoting.Channels,
System.Runtime.Remoting.Channels.Http,
System.Runtime.Remoting.Channels.Tcp, and System.IO.
3. Specify the namespace Lab13, and in it, create a class named TestClient.
In subsequent steps of this exercise, you will code the Main method.
4. In the Main method of TestClient:
Create and register an HTTP channel and a TCP channel.
5. Invoke the Activator.GetObject method to create an AServer instance of
type Lab13.AServer named aServer at the following URL:
http://localhost:8086/DoAuthentication

6. Invoke the Activator.GetObject method to create an FServer instance of

type Lab13.FServer named fServer at the URL:
tcp://localhost:8085/DoFulfillment

7. In the try section of a try/catch block:

a. Invoke the Authenticate method of the aServer object, and use 1234 as
the customer’s ID. Print a message with the result to the console.
b. If authentication passes, call the fServer object’s Fulfill method. Use
1234 as the customer’s ID and 5678 as the item number. Print a message
with the result to the console.
8. In the catch section of the try/catch block:
a. Catch any exceptions of type IOException, and print out their content.
b. Return a value of 1.
9. In a Visual Studio .NET Command Prompt window, build Testclient.exe.

Important Do not forget to reference Authenticate.exe, and

Fulfillment.exe in the command line.
Module 13: Remoting and XML Web Services 35

10. Test the order system.

a. Ensure that no server application is running and listening on ports 8085
and 8086.

Tip You can display your machine’s current TCP/IP network connections
by running the program netstat in a command prompt window. The
following example shows that port 7 is in use by a process with PID 1504:
C:\>netstat -o -n -a

Active Connections

Proto Local Address Foreign Address State PID

TCP 0.0.0.0:7 0.0.0.0:0 LISTENING 1504 …

b. Open two separate console windows. In one window, run

Fulfillment.exe, and in the other window, run Authenticate.exe.
c. Open a third console window and repeatedly run Testclient.exe.
The console output will vary because the random-number generator
values cause authentication and fulfillment to succeed or fail 50 percent
of the time.
A typical series of test client invocations would produce output similar
to the following:
>testclient
Authentication Server Customer 1234 Authorization: False

>testclient
Authentication Server Customer 1234 Authorization: False

>testclient
Authentication Server Customer 1234 Authorization: True
Fulfillment Server Customer 1234 Item Number 5678
Shipped: False

>testclient
Authentication Server Customer 1234 Authorization: True
Fulfillment Server Customer 1234 Item Number 5678
Shipped: True
36 Module 13: Remoting and XML Web Services

" XML Web Services

Topic Objective
To provide an overview of
the topics covered in this
section. ! ASP.NET XML Web Services Overview
Lead-in ! ASP.NET Features
In this section, you will learn
how to use Visual Studio ! Consuming an XML Web Service
.NET to implement an
ASP.NET XML Web service ! XML Web Service Discovery
and how to access the XML
Web service from a Web
browser and a client
application.

*ILLEGAL FOR NON-TRAINER USE**

XML Web services can be provided by and accessed from applications that
reside in a variety of hosts. Hosts include, but are not limited to, ASP.NET,
Microsoft Internet Explorer, executable files, Microsoft Windows® NT® Server,
and Microsoft Windows 2000 Component Services, also known as COM+
Services.
In the preceding sections, you have learned how to use .NET Remoting to
create executable files that host XML Web services by using the default HTTP
channel with SOAP formatting.
In this section, you will learn how to use Visual Studio .NET to implement an
ASP.NET XML Web service and how to access this XML Web service from
both a Web browser and a client application.
Module 13: Remoting and XML Web Services 37

ASP.NET XML Web Services Overview

! ASP.NET Files with .asmx Extensions Are Web Services
Topic Objective
To provide an overview of ! Example of HelloWorld .asmx File
ASP.NET XML Web
<%@
<%@ WebService
WebService Language="C#"
Language="C#" Class="HelloWorld"
Class="HelloWorld" %>
%>
services. using
using System;
System;
Lead-in using
using System.Web.Services;
System.Web.Services;
ASP.NET provides support public
public class
class HelloWorld
HelloWorld :: WebService
WebService {{
for XML Web services with [WebMethod]
[WebMethod] public
public String
String SayHelloWorld()
SayHelloWorld() {{
return
return "Hello
"Hello World";
World";
the .asmx file, which is a
}}
text file that is similar to an
}}
.aspx file.
! If File Is Placed on Server Foo Inside a Virtual Directory Bar
# Access service by using:
http://Foo/Bar/HelloWorld.asmx
http://Foo/Bar/HelloWorld.asmx
# Access WSDL of service by using:
http://Foo/Bar/HelloWorld.asmx?wsdl
http://Foo/Bar/HelloWorld.asmx?wsdl
*****************************ILLEGAL FOR NON-TRAINER USE******************************
This section introduces some of the basic features of ASP.NET that enable
developers to host and use XML Web services. The Internet is quickly evolving
from its present stage where Web sites deliver user interface (UI) pages to Web
browsers to a next generation of programmable Web sites that directly link
organizations, applications, services, and devices. These programmable Web
sites are more than passively accessed sites; they are reusable, intelligent XML
Web services.

Using .asmx Files

ASP.NET provides support for XML Web services with the .asmx file. An
.asmx file is a text file that is similar to an .aspx file. An .asmx file can be part
of an ASP.NET application that includes .aspx files. Like .aspx files, .asmx files
are automatically compiled by the ASP.NET runtime when a request to the
service is made. Subsequent requests are serviced by a cached pre-compiled
type object. Like .aspx files, .asmx files are then Uniform Resource Identifier-
addressable.
The following example shows the code that is contained in the
Delivery Tip HelloWorld.asmx file. It is a simple example of a ASP.NET-hosted XML Web
You can demonstrate the
SayHelloWorld service by
service.
cutting and pasting the <%@ WebService Language="C#" Class="HelloWorld" %>
HelloWorld.asmx code into
Notepad and saving it as a
using System;
file named HelloWorld.asmx
in the source directory for an using System.Web.Services;
existing IIS virtual directory.
You then type the public class HelloWorld : WebService {
appropriate URL in the
Internet Explorer Address [WebMethod] public String SayHelloWorld() {
bar. To make the Address return "Hello World";
bar visible, click the View }
menu, point to Toolbars,
and then click Address Bar. }
38 Module 13: Remoting and XML Web Services

The HelloWorld.asmx file starts with an ASP.NET directive, WebService, and

sets the language to C#. You can also set the language to Microsoft
Visual Basic®.
The class HelloWorld contains the XML Web service and therefore is derived
from the base class WebService in the System.Web.Services namespace. All
of the methods that will be accessible as part of the service must have the
custom attribute, [WebMethod], in front of their signatures. In the preceding
example, the SayHelloWorld method is the service’s only method.

Using a Virtual Directory

To create an ASP.NET application, you can use an existing virtual directory or
create a new one. For example, if you installed Microsoft Windows 2000 Server
and Internet Information Server (IIS) on a computer, that computer probably
now has the directory C:\InetPub\WWWRoot.
To configure IIS, start the Internet Information Services tool. Click Start,
click Control Panel, Performance and Maintenance, Administrative Tools,
and then click Internet Information Services. In the Internet Information
Services tool, you can create a new virtual directory or promote an existing
directory.
! To create a new virtual directory, right-click an existing directory, and then
click New.
! To promote an existing directory, right-click a virtual directory, click
Properties and then set the Local Path.

If you place the HelloWorld.asmx file on a server called Foo inside a virtual
directory called Bar, you can use a URL in Internet Explorer to test the
application. For example, if you type http://Foo/Bar/HelloWorld.asmx in the
Address bar, the resulting page shows the public methods for this XML Web
service and the protocols, such as SOAP or HTTP GET, that you can use to
invoke these methods.
The public methods for the XML Web service are marked with the
[WebMethod] attribute.
The Web Services Description Language XML file for this service is produced
when you type http://Foo/Bar/HelloWorld.asmx?WSDL in the
Internet Explorer Address bar. This WSDL file is important and can be used
by clients to access the service.
Module 13: Remoting and XML Web Services 39

ASP.NET Features
! ASP.NET Can Expose Web Services Defined in a .NET Class
Topic Objective
To explain how to create an # Class derives from WebService, method attribute [WebMethod]
XML Web service by namespace
namespace MyNameSpace
MyNameSpace {{
exposing a .NET class that public
public class
class HelloWorld
HelloWorld :: WebService
WebService {{
inherits from the [WebMethod]
[WebMethod] public
public String
String SayHelloWorld()
SayHelloWorld() {{
WebService class, and to return "Hello World";
return "Hello World"; } }
introduce advanced }}
ASP.NET features. }} #

Lead-in # Class source file is compiled into a library DLL and placed in \Bin
In ASP.NET, you can create
csc
csc /out:bin\helloworld.dll
/out:bin\helloworld.dll /t:library
/t:library helloworld.cs
helloworld.cs
an XML Web service by
simply exposing a .NET # The .asmx file contains a single line that names the class
class that inherits from the
WebService class. <%@
<%@ WebService
WebService Class="MyNameSpace.HelloWorld"
Class="MyNameSpace.HelloWorld" %>
%>
! Advanced ASP.NET Features
# Data sets, Global.asax, Session and Application objects, pattern matching

*ILLEGAL FOR NON-TRAINER USE**

In ASP.NET, you can create an XML Web service by simply exposing a .NET
class that inherits from the WebService class. You compile the class’s source
file into a library DLL and place this DLL in the ASP.NET application’s \Bin
subdirectory. You then create in the ASP.NET application’s directory an .asmx
file that contains only the following single line of code:
<%@ WebService Class="<namespace>.<classname>" %>

The HelloWorld.cs source code defines a HelloWorld service with an exported

SayHelloWorld method in the MyNameSpace namespace, as shown in the
following example:
using System;
using System.Web.Services;

namespace MyNameSpace {

public class HelloWorld : WebService {

[WebMethod] public String SayHelloWorld() {
return "Hello World";
}
}

To compile this HelloWorld.cs file in the ASP.NET application directory, you

type the following command in a Visual Studio .NET Command Prompt
window:
>csc /out:bin\helloworld.dll /t:library helloworld.cs
40 Module 13: Remoting and XML Web Services

You then create the file named HelloWorld.asmx in the ASP.NET application
directory. HelloWorld.asmx contains the following single line of code:
<%@ WebService Class="MyNameSpace.HelloWorld" %>

The only methods that are exposed from a service are those class methods that
are flagged with a [WebMethod] custom attribute. Without this attribute, the
method is not exposed from the service. Not exposing a method from a service
is useful when you want to hide implementation details that are called by public
XML Web service methods or when the WebService class is also used in local
applications.

Note A local application can use any public method, but only [WebMethod]
methods are remotely accessible through SOAP.

Advanced ASP.NET Features

ASP.NET is also useful for building complex XML Web services. Advanced
ASP.NET features include:
! Data sets
Data sets are a powerful new XML-based technique to represent
disconnected data. Data sets can be returned from an XML Web service
method. Because Data sets can store complex information and relationships
in an intelligent structure, they enable you to take full advantage of XML
Web services. When you expose Data sets through a service, you can limit
the database connections to your data server.
! Global.asax file
The Global.asax file adds application-level logic and event-handling code to
Web applications.
! Session and Application objects
You can use ASP.NET intrinsics, such as the Session and Application
objects, to manage an ASP.NET application’s state.
! Text Pattern Matching
Text Pattern Matching is a technology that can be used to address any
Uniform Resource Identifier that returns text as if it were an XML Web
service.

Further discussion of these and other advanced ASP.NET features is beyond the
scope of this course.
Module 13: Remoting and XML Web Services 41

Demonstration: Using Visual Studio .NET to Create an XML Web

Service
Topic Objective
To demonstrate how to use
Visual Studio .NET to
create an XML Web service.
Lead-in
In this demonstration, you
will learn how to create a
service called MathService
that has a single method
named SalesTax.

*ILLEGAL FOR NON-TRAINER USE**

In this section, you have learned how to create an XML Web service by using
ASP.NET. Visual Studio .NET provides an even easier way to build ASP.NET-
hosted XML Web services.
In this demonstration, you will see how to create a service called MathService
that has a single method named SalesTax. The SalesTax method takes two
parameters: The first parameter represents the sales amount; and the second
parameter represents the fractional sales tax rate. For example, a sales tax rate
of 8.5 percent is represented as .085. SalesTax returns a total amount that is
equal to the sales amount plus the sales tax.

! To create a service called MathService that has a single method named

SalesTax
1. Start Visual Studio, and create a new project.
Delivery Tip
Although this demonstration a. In the New Project dialog box, select Visual C# Projects as the type.
includes detailed
b. Select ASP.NET Web Service as the template. You may need to scroll
instructions, it is not a
guided practice. Present the
down to see ASP.NET Web Service.
demonstration and suggest c. In the Location box, type the name of the Web server,
that students try the http://localhost/MathService. The grayed out Name box will now
demonstration for contain the text MathService. Then click OK.
themselves later.
2. On the View menu, click Code.
3. Because the XML Web service in this demonstration is simple, you can
work on the code directly. For more complex XML Web services, you can
use the Service1.asmx.cs Design palette that is displayed when you create a
new project of type XML Web service. The Service1.asmx.cs Design palette
enables the drag-and-drop operation of rapid application development that
can make complex services easier to set up.
4. In the Service1 class, examine the HelloWorld method in the commented-
out WEB SERVICE EXAMPLE.
42 Module 13: Remoting and XML Web Services

5. In Service1.asmx.cs, implement the SalesTax method by inserting the

following code after the comments for the HelloWorld method. You should
leave the HelloWorld code commented out.
[WebMethod] public float SalesTax(
float salesAmount, float fractionalTaxRate) {
return salesAmount +
(salesAmount * fractionalTaxRate);
}

6. On the Build menu, click Build Solution to create the XML Web service.
7. Use Internet Explorer to access the XML Web service at the following
URL:
http://localhost/MathService/Service1.asmx

Tip To use Internet Explorer to view an XML Web service from within the
Visual Studio environment, right-click the .asmx file in the Solution
Explorer window, and then click View in Browser.

8. In the Internet Explorer page that is returned in step 7, click the link for the
Service1 operation labeled SalesTax.
9. In the Internet Explorer page that is returned in step 8, enter some
parameters, and then click Invoke to verify that the correct value is returned
and displayed in SOAP/XML format.
10. Use Internet Explorer to access and verify that the XML Web service’s
description is obtained from the following URL:
http://localhost/MathService/Service1.asmx?wsdl
Module 13: Remoting and XML Web Services 43

Consuming an XML Web Service

Topic Objective ! To Consume a Web Service, Use Wsdl.exe
To explain how XML Web
services are consumed and # Identify the object or service URI to be used
how to use the Web http://localhost/MathService/Service1.asmx
Services Description http://localhost/MathService/Service1.asmx
Language tool. # Run Wsdl.exe on the service’s URI
Lead-in
In addition to providing wsdl
wsdl http://localhost/MathService/Service1.asmx?wsdl
http://localhost/MathService/Service1.asmx?wsdl
technology that enables you
to create XML Web # Write the client code that calls the remote object
services, the .NET Service1
Service1 salesTaxService
salesTaxService == new
new Service1();
Service1();
Framework provides a float
float totalAmount
totalAmount == salesTaxService.SalesTax(
salesTaxService.SalesTax(
sophisticated set of tools amount,taxRate);
amount,taxRate);
and code to consume XML
Web services. # Build the client and proxy code

csc
csc salestaxclient.cs
salestaxclient.cs service1.cs
service1.cs

*ILLEGAL FOR NON-TRAINER USE**

In addition to providing technology that enables you to create XML Web
services, the .NET Framework provides a sophisticated set of tools and code to
consume XML Web services. Consuming an XML Web service means
accessing it as a client. Because XML Web services are based on open
protocols, such as SOAP and HTTP, this client technology can also be used to
consume XML Web services that are not built by using the .NET Framework.

Using the Web Services Description Language Tool

The .NET Framework SDK provides a tool that is called the Web Services
Description Language tool (Wsdl.exe). You can use this tool to download the
WSDL description of an XML Web service and create a proxy class that
addresses this service. For XML Web services that are created by using
ASP.NET, the proxy class is similar to the class that is defined in the .asmx file.
However, the proxy class contains only methods with the [WebMethod]
custom attribute.
An application that uses an XML Web service creates an instance of the
service’s proxy class and invokes the service’s methods as it would with any
local object. You compile and build your code with this proxy class included.
Alternatively, you can use features of the Visual Studio environment to build
applications that consume XML Web services. These Visual Studio features are
beyond the scope of this course.
44 Module 13: Remoting and XML Web Services

The following process shows how to create a simple application that uses the
XML Web service that is created in the Using Visual Studio to Create an XML
Web service demonstration in this module.

Delivery Tip ! To use the Service1 Web Service

The use of the Web 1. Identify the object and the service that should be used.
Services Description
Language tool (Wsdl.exe) is The Salestaxclient application will use the SalesTax method of the Service1
covered in detail because service whose URL is:
the students will need this
http://localhost/MathService/Service1.asmx
information to do Lab 13.2,
Using an XML Web service.
If you feel that students may
Note Typically a client uses an XML Web service that is located on a
benefit from a full
demonstration, you can
remote computer. If Service1 were located in a MathService virtual
demonstrate the steps here. directory on a Web server named foo, the URL for the service would be:
http://foo/MathService/Service1.asmx

2. Run the WSDL tool, Wsdl.exe, and point it at the URL where the server
object is located.
You can request that the Web Service Utility retrieves the schema and, from
it, generates a source file that contains a proxy for the service’s class.
To generate a proxy for the Service1 class in a file named Service1.cs, type
the following command in a Visual Studio .NET Command Prompt
window:
wsdl http://localhost/MathService/service1.asmx?wsdl
Module 13: Remoting and XML Web Services 45

The proxy, Service1.cs, contains code similar to the following:

//...
using System.Diagnostics;
using System.Xml.Serialization;
using System;
using System.Web.Services.Protocols;
using System.ComponentModel;
using System.Web.Services;
//...
[System.Diagnostics.DebuggerStepThroughAttribute()]
[System.ComponentModel.DesignerCategoryAttribute("code")]
[System.Web.Services.WebServiceBindingAttribute!
(Name="Service1Soap", Namespace="http://tempuri.org/")]
public class Service1 :
System.Web.Services.Protocols.SoapHttpClientProtocol {
//...
public Service1() {
this.Url =
"http://localhost/mathservice/service1.asmx";
}
//...
[System.Web.Services.Protocols.SoapDocumentMethodAttribute
!
("http://tempuri.org/SalesTax",
Use=System.Web.Services.Description.SoapBindingUse.Literal,
ParameterStyle=
System.Web.Services.Protocols.SoapParameterStyle.Wrapped)]
public System.Single SalesTax(System.Single salesAmount,
System.Single fractionalTaxRate) {
object[] results =
this.Invoke("SalesTax",
new object[] {salesAmount,
fractionalTaxRate});
return ((System.Single)(results[0]));
}
//...
46 Module 13: Remoting and XML Web Services

3. Write the client code that calls the remote object. Create a text file named
Salestaxclient.cs in the folder <install folder>\DemoCode\Mod13\
Demo13.2 containing the following code:
using System;

public class Class1 {

public Class1() {}
public static int Main(string[] args) {
Console.WriteLine("Enter Sales Amount:");
float amount = Single.Parse(Console.ReadLine());
Console.WriteLine(
"Enter Fractional Sales Tax Rate:");
float taxRate = Single.Parse(Console.ReadLine());
Service1 salesTaxService = new Service1();
float totalAmount =
salesTaxService.SalesTax(amount,taxRate);
Console.WriteLine(
"Total: {0}",totalAmount.ToString());
return 0;
}
}

4. Build the client executable file by using the client code and proxy code. You
must include references to the assemblies that are used by the client and
proxy code.
5. To build Salestaxclient.exe, type the following command in a Visual Studio
.NET Command Prompt window:
csc salestaxclient.cs service1.cs

6. Run the client, and enter parameters as prompted.

Running Salestaxclient.exe produces output that should be similar to the
following:
salestaxclient
Enter Sales Amount:
100
Enter Fractional Sales Tax Rate:
.08
Total: 108
Module 13: Remoting and XML Web Services 47

XML Web Service Discovery

Topic Objective
To introduce the Web ! Discovery – The Process of Locating and Interrogating XML Web
Service discovery process Service Descriptions
and the tools that are ! Discovery Services Are Evolving and Changing Rapidly
available for discovery.
! Disco – Microsoft XML Web Services Discovery Tool
Lead-in
Web Service discovery is # Disco file is an XML document that links to descriptions of XML Web
Services
the process of dynamically
locating and interrogating # Disco file is currently created and used by Visual Studio
Web Service descriptions, ! Universal Description, Discovery, and Integration Project
which is a preliminary step
for accessing an XML Web # Open framework for describing services, discovering businesses,
service. and integrating business services that use the Internet
# Cross-industry support and platform independence
# For more information, see http://www.uddi.org

*ILLEGAL FOR NON-TRAINER USE**

Web Service discovery is the process of dynamically locating and interrogating
Web Service descriptions, which is a preliminary step for accessing an XML
Web service. The discovery process allows an XML Web service client that
may not know the Web Service’s Uniform Resource Identifier to locate an
XML Web service, to determine the capabilities of that Web Service, and to
properly interact with it.
Web Service discovery is currently evolving, and the information that is
presented in this topic is subject to change.

Disco – Microsoft Web Services Discovery Tool

In the current version of the .NET Framework, you can enable programmatic
discovery when an XML Web service publishes a file with a .disco extension.
Disco is the Microsoft XML Web services discovery tool. A .disco file is an
XML document that contains links to other resources that describe the XML
Web service. Currently, when you create an ASP.NET-hosted XML Web
service with Visual Studio .NET, .disco files are automatically generated and
used.
For more information about Disco, see the Visual Studio .NET and .NET
Framework SDK documentation.

Universal Description, Discovery, and Integration

The Universal Description, Discovery and Integration (UDDI) project is a
cross-industry project that is dedicated to creating a platform-independent, open
framework for describing Web Services, discovering businesses, and
integrating business services that use the Internet. The project is driven by all of
the major platform and software providers, marketplace operators, and
e-business leaders.
For more information about UDDI, see the UDDI Web site at
http://www.uddi.org/.
48 Module 13: Remoting and XML Web Services

Lab 13.2: Using an XML Web Service

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will access
an XML Web service by
creating a proxy using the
Web Services Description
Language tool.

*ILLEGAL FOR NON-TRAINER USE**

Objectives
After completing this lab, you will be able to:
• Access an XML Web service by creating a proxy using the Web Services
Description Language tool.

Lab Setup
Starter and solution files are associated with this lab. The starter files are in the
folder <install folder>\Labs\Lab13.2\Starter. The solution files for this lab are
in the folder <install folder>\Labs\Lab13.2\Solution.
Module 13: Remoting and XML Web Services 49

Scenario
This lab is similar to the scenario used in Lab 13.1, Building an Order-
Processing Application by Using Remoted Servers. That scenario was based on
a simple distributed order-processing application, in which a customer specifies
a customer ID and an item number for an item that the customer wants to
purchase, and the application processes the order. The order processing
involves authenticating the customer’s ID and arranging order fulfillment that is
to say, having the ordered item sent to the customer.
This lab extends Lab 13.1 by having the client application calculate the cost of
the ordered item. Your client will use an XML Web service to calculate the
item’s cost including sales tax. This scenario simulates the case where you do
not have access to the XML Web service’s source code or assembly.
You will build a MathService XML Web service to calculate the total cost of an
item given the pretax cost and fractional tax rate. You will then use the Web
Services Description Language tool (Wsdl.exe) to access and create a .NET
proxy class for this XML Web service. Then you will build a client called
Testclient2.exe that uses this proxy to access the XML Web service’s
Service1.SalesTax method to calculate the cost of the ordered item.

Estimated time to complete this lab: 55 minutes

50 Module 13: Remoting and XML Web Services

Exercise 1
Creating the XML Web Service Proxy
In this exercise, you will create the MathService XML Web service and use the
Web Services Description Language tool (Wsdl.exe) to create a proxy class to
this XML Web service.

! Create the MathService XML Web service using Visual Studio .NET
1. Start Visual Studio, and create a new project.
a. In the New Project dialog box, select Visual C# Projects as the type.
b. Select ASP.NET Web Service as the template. You may need to scroll
down to see ASP.NET Web Service.
c. In the Location box, type the name of the Web server,
http://localhost/MathService. The grayed out Name box will now
contain the text MathService. Then click OK.
2. On the View menu, click Code.
Because the XML Web service in this demonstration is simple, you can
work on the code directly. For more complex XML Web services, you can
use the Service1.asmx.cs Design palette that is displayed when you create a
new project of type XML Web service. The Service1.asmx.cs Design palette
enables the drag-and-drop operation of rapid application development that
can make complex services easier to set up.
3. In the Service1 class, examine the HelloWorld method in the commented-
out WEB SERVICE EXAMPLE.
4. In Service1.asmx.cs, implement the SalesTax method by inserting the
following code after the comments for the HelloWorld method. You should
leave the HelloWorld code commented out.
[WebMethod] public float SalesTax(
float salesAmount, float fractionalTaxRate) {
return salesAmount +
(salesAmount * fractionalTaxRate);
}

5. On the Build menu, click Build Solution to create the XML Web service.
6. Use Internet Explorer to access the XML Web service at the following
URL:
http://localhost/MathService/Service1.asmx

Tip To use Internet Explorer to view an XML Web service from within the
Visual Studio environment, right-click the .asmx file in the Solution
Explorer window, and then click View in Browser.
Module 13: Remoting and XML Web Services 51

7. In the Internet Explorer page that is returned in step 6, click the link for the
Service1 operation labeled SalesTax.
8. In the Internet Explorer page that is returned in step 7, type some
parameters, and then click Invoke to verify that the correct value is returned
and displayed in SOAP/XML format.
9. Use Internet Explorer to access and verify that the XML Web service’s
description is obtained from the following URL:
http://localhost/MathService/Service1.asmx?wsdl

! Create the XML Web service proxy

Important To use Microsoft Visual Studio .NET tools within a command
prompt window, the command prompt window must have the proper
environment settings. The Visual Studio .NET Command Prompt window
provides such an environment. To run a Visual Studio .NET Command Prompt
window: on the Start menu, point to All Programs, point to Microsoft Visual
Studio .NET, Visual Studio .NET Tools, and then click Visual Studio .NET
Command Prompt.

• In a Visual Studio .NET Command Prompt window, from the Lab 13.2
Starter directory, create a proxy to the authentication XML Web service
named Service1.cs by running the following command:
wsdl http://localhost/MathService/service1.asmx?wsdl
52 Module 13: Remoting and XML Web Services

Exercise 2
Creating the Test Client
In this exercise, you will create a test client. The client calls the authentication
server. If the user is authenticated, then the client calls the order fulfillment
server. If the order is fulfilled, then the client calls the MathService XML Web
service to calculate the total cost including sales tax. For simplicity, the client
will assume that all items cost $100 and that the sales tax rate is always 0.1.

! Create the test client

1. Use the editor of your choice to examine the C# source file that is named
Testclient2.cs located in the Lab13.2 Starter directory.
2. Add code to Testclient2.cs after the following command that outputs the
results from calling the fulfillment service:
Console.WriteLine(
"Fulfillment Server Customer 1234 Item Number 5678
Shipped: {0}", shipped.ToString() );

The code should check the status of fulfillment. If shipped is true, then
perform the following steps:
a. Instantiate a new Service1 object named salesTaxService.
b. Call the salesTaxService.SalesTax method, passing 100.0F as its first
argument and 0.1F as its second argument.
c. Print out to the console the returned total cost value.
3. Build Testclient2.exe in a Visual Studio .NET Command Prompt window as
follows:
a. Reference Fulfillment.exe, and Authenticate.exe.
b. Specify the C# source files, Service1.cs and Testclient2.cs.
c. Specify that the output file should be named Testclient2.exe.
Module 13: Remoting and XML Web Services 53

4. Test the order fulfillment system, by performing the following steps:

a. In a console window, from the Lab 13.2 Starter directory, run
Authenticate.exe.
b. In a second console window, from the Lab 13.2 Starter directory, run
Fulfillment.exe.
c. In a third console window, repeatedly run Testclient2.exe.
The console output will vary because the random-number generator
values cause authentication and fulfillment to succeed or fail 50 percent
of the time.
A typical series of test client invocations would produce output similar
to the following:
>testclient2
Authentication Server Customer 1234 Authorization: True
Fulfillment Server Customer 1234 Item Number 5678!
Shipped: True
Total Cost: 110

>testclient2
Authentication Server Customer 1234 Authorization: True
Fulfillment Server Customer 1234 Item Number 5678!
Shipped: False
54 Module 13: Remoting and XML Web Services

Review
Topic Objective
To reinforce module
objectives by reviewing
key points. ! Remoting
Lead-in ! Remoting Configuration Files
The review questions cover
some of the key concepts ! XML Web Services
taught in the module.

*ILLEGAL FOR NON-TRAINER USE**

1. Can two application domains that are on the same computer each have a
channel that listens on the same port number?
Ports are a machine-wide resource; therefore, on one computer, it is
illegal to register multiple channels that listen on the same port
number, even if the channels are registered in different application
domains.

2. What is the purpose of a proxy?

The proxy object acts as a representative of the remote object and
ensures that all calls that are made on the proxy are forwarded to the
correct remote object instance. All methods that are called on the proxy
are automatically forwarded to the remote class, and any results are
returned to the client.

3. Can a remotely instantiated object be returned by value?

No. All objects that are instantiated remotely are returned by reference.

4. What determines whether a remotely instantiated object’s parameters and

return values are passed by reference or by value?
Objects whose classes are marked with the SerializableAttribute are
marshal-by-value, and objects that inherit from
System.MarshalByRefObject are marshal-by-reference.
Module 13: Remoting and XML Web Services 55

5. What file extension is typically used by ASP.NET-hosted XML Web

services?
ASP.NET provides support for XML Web services with the .asmx file.

6. In ASP.NET, how do you specify that a service is defined in a prebuilt

assembly, and where should that assembly’s DLL be located in relation to
the ASP.NET application?
The .asmx file should contain the single line:
<%@ WebService Class="<namespace>.<classname>" %>
The assembly library DLL should be in the application’s \Bin
subdirectory.

7. How can a client invoke an XML Web service that is not implemented by
using the .NET Framework or in which the XML Web service’s assembly or
source code is not available?
The Web Services Description Language tool (Wsdl.exe) can be used to
read the WSDL description of an XML Web service and create a proxy
class. The client can use the proxy class to invoke the methods of the
XML Web service.
56 Module 13: Remoting and XML Web Services

*ILLEGAL FOR NON-TRAINER USE**

Your evaluation of this course will help Microsoft understand the quality of
your learning experience.
To complete a course evaluation, go to http://www.metricsthatmatter.com/
survey/.
Microsoft will keep your evaluation strictly confidential and will use your
responses to improve your future learning experience.

THIS PAGE INTENTIONALLY LEFT BLANK

Module 14 (Optional):
Threading and
Asynchronous
Contents
Programming
Overview 1
Introduction to Threading 2
Using Threads in .NET 9
Thread Safety 29
Special Thread Topics 51
Asynchronous Programming in .NET 74
Lab 14: Working With Multithreaded
Applications 92
Review 108
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, places or events is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Module 14 (Optional): Threading and Asynchronous Programming iii

Instructor Notes Module 14

Presentation: This module provides students with knowledge about the support that the
150 Minutes Microsoft® .NET Framework provides for working with multithreaded
applications and asynchronous programming.
Lab:
60 Minutes After completing this module, students will be able to:
! Create and manage threads.
! Create thread-safe code.
! Create and use timers.
! Create threads using thread pools.
! Create managed threads that interact well with COM components.
! Create Microsoft Windows® Forms applications with background threads.
! Make asynchronous calls using delegates.

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach
this module.

Required Materials
To teach this module, you need the Microsoft PowerPoint® file 2349B_14.ppt.

Preparation Tasks
To prepare for this module:
! Read all of the materials for this module.
! Practice the demonstrations.
! Complete the lab.
iv Module 14 (Optional): Threading and Asynchronous Programming

Demonstrations
This section provides demonstration procedures that will not fit in the margin
notes or are not appropriate for the student notes.
The code for each of the following demonstrations is contained in project
folders that are located in <install folder>\Democode\Mod14.
Use the debugger to step through the code while you point out features and ask
students what they think will happen next.

Managing Threads
In this demonstration, you will show students how to create and manage threads
in the .NET Framework by using some of the classes and methods that were
covered in Using Threads in .NET.
The code for this demonstration is contained in one project and is located in
<install folder>\Democode\Mod14\Demo14.1.

Interrupt and Abort

In this demonstration, you will show students how to terminate threads by using
the Thread.Interrupt and Thread.Abort methods.
The code for this demonstration is contained in one project and is located in
<install folder>\Democode\Mod14\Demo14.2.

Using Synchronization Contexts and Synchronized Code

Regions to Provide Thread Safety
In this demonstration, you will use a series of tests to show students how to
achieve thread safety through the use of synchronization contexts and
synchronized code regions.
The code for this demonstration is contained in one project and is located in
<install folder>\Democode\Mod14\Demo14.3.

Using Synchronization Techniques and Thread Pooling

In this demonstration, you will show students how to perform synchronization
by using the C# lock keyword and manual synchronization primitives, and also
how to obtain multiple threads by using a thread pool.
The code for this demonstration is contained in one project and is located in
<install folder>\Democode\Mod14\Demo14.4.
Module 14 (Optional): Threading and Asynchronous Programming v

Windows Forms Threading

In this demonstration, you will show students how to use a background thread
in a Windows Forms application.
The code for this demonstration is contained in one project and is located in
<install folder>\Democode\Mod14\Demo14.5.

Asynchronous File Stream Read

In this demonstration, you will show students how to use synchronous and
asynchronous read methods on a file stream. For the asynchronous case, you
will show four different ways to complete the operation: callback, poll, end
method call, and wait with timeout.
The code for this demonstration is contained in one project and is located in
<install folder>\Democode\Mod14\Demo14.6.

Using a Delegate
In this demonstration, you will show students how to use a delegate object to
make asynchronous calls.
The code for this demonstration is contained in one project and is located in
<install folder>\Democode\Mod14\Demo14.7.

Multimedia Presentation
This section lists the multimedia items that are part of this module. Instructions
for launching and playing the multimedia are included with the relevant slides.

Asynchronous Programming
This animation illustrates the .NET Framework common language runtime
support for asynchronous programming using Delegate objects.
vi Module 14 (Optional): Threading and Asynchronous Programming

Module Strategy
Use the following strategy to present this module:
! Introduction to Threading
Provide a general introduction to the concept of threads and discuss
advantages and disadvantages of using them. As a simple illustration of the
concept of threading, use Microsoft Internet Explorer to show how you can
still do work while waiting for a download operation to complete.
Provide a high level overview of the System.Threading namespace and
introduce the asynchronous design pattern, which you will cover in more
detail in Asynchronous Programming in .NET.
Explain how application domains play a key role in .NET threading
architecture.
! Using Threads in .NET
Focus on the classes in the System.Threading namespace that are used to
start, manage, and terminate threads.
In addition to the preceding operations, discuss the role of managed thread
local storage.
! Thread Safety
Focus on the issues that students may encounter in multithreaded
programming from sharing data and resources between threads, as a result
of thread synchronization.
Introduce strategies that the .NET Framework provides for dealing with
synchronization, in particular classes and interfaces in System.Threading.
! Special Thread Topics
Introduce the Thread.Timer class, which provides a mechanism for
executing methods at specified intervals. Explain how a TimerCallback
delegate is used in conjunction with a Timer.
Discuss the use of thread pools in making multiple threads operate more
efficiently.
Discuss how managed threads call into a COM object.
Outline best practices for implementing thread-safe code.
Module 14 (Optional): Threading and Asynchronous Programming vii

! Asynchronous Programming in .NET

Provide a brief definition of the concept of asynchronous programming as
the ability to issue method calls to other components, and to carry on with
other work without waiting for the operation to complete.
Introduce the asynchronous design pattern, and emphasize that one of its
innovations is that the caller can decide whether a particular call should be
asynchronous.
Spend most of the time in this section on the Asynchronous File Stream
Read Example. In addition to the code on the slides and information in the
Student Notes, there is an accompanying demonstration.
Discuss the use of Asynchronous delegates to call a synchronous method in
an asynchronous manner.
Play the Asynchronous Programming animation to illustrate the .NET
Framework common language runtime support for asynchronous
programming using Delegate objects.
Module 14 (Optional): Threading and Asynchronous Programming 1

Overview
Topic Objective
To provide an overview of
the module topics and
objectives.
! Introduction to Threading
Lead-in ! Using Threads in .NET
In this module, you will learn
about the support that the ! Thread Safety
.NET Framework provides
for working with ! Special Thread Topics
multithreaded applications
! Asynchronous Programming in .NET
and asynchronous
programming.

*ILLEGAL FOR NON-TRAINER USE**

In this module, you will learn about the support that the Microsoft® .NET
Framework provides for working with multithreaded applications and
asynchronous programming. The common language runtime abstracts much of
the threading support into classes that greatly simplify most threading tasks.
Even if you do not create your own threads explicitly, you need to understand
how your code should handle multiple threads if it is run in a multithreaded
environment.
You will also learn how to handle thread synchronization to maintain
application responsiveness and avoid potential data corruption and other
problems.
In the .NET Framework, asynchronous programming is a feature that is
supported by Remoting, Networking: HTTP, TCP, File I/O, ASP.NET, and
Microsoft Message Queue Server (MSMQ). Because asynchronous
programming is a core concept, the .NET Framework provides a common
design pattern for handling asynchronous execution. This module introduces the
.NET Framework asynchronous Design Pattern and gives examples of its use.
After completing this module, you will be able to:
! Create and manage threads.
! Create thread-safe code.
! Create and use timers.
! Create threads using thread pools.
! Create managed threads that interact well with COM components.
! Create Microsoft Windows® Forms applications with background threads.
! Make asynchronous calls using delegates.
2 Module 14 (Optional): Threading and Asynchronous Programming

" Introduction to Threading

Topic Objective
To provide an overview of
the topics that you will cover
in this section. ! Overview of Threads
Lead-in ! Overview of Support for Threading in .NET
In this section, you will learn
about the advantages and ! Thread Architecture in .NET
disadvantages of using
threads and the support for
threads that is provided by
the .NET Framework.

*ILLEGAL FOR NON-TRAINER USE**

In this section, you will learn about the advantages and disadvantages of using
threads and the support for threads that is provided by the .NET Framework.
Module 14 (Optional): Threading and Asynchronous Programming 3

Overview of Threads
Topic Objective
To define threads in the
context of general ! Threads
multitasking and state the # The basic unit to which an operating system allocates processor time
primary advantages and # Enable multiple activities to appear to occur simultaneously
disadvantages of using
! Advantages of using multiple threads
threads.
# Application does background processing while keeping the UI responsive
Lead-in
Whether you are developing # Distinguish tasks of varying priority
for computers with one # Communicate over a network, to a Web server, and to a database
processor or several, you ! Potential disadvantages of using threads
want your application to
# Diminished performance due to increased operating system overhead, for
provide the most responsive example, thread context switching
interaction with the user,
even if the application is # Controlling code execution with many threads is complex, and can be a
source of many difficult to find and fix bugs
currently doing other work.

*ILLEGAL FOR NON-TRAINER USE**

Whether you are developing for computers with one processor or several, you
want your application to provide the most responsive interaction with the user,
even if the application is currently doing other work. Using multiple threads of
execution is one of the most powerful ways to keep your application responsive
to the user and at the same time make use of the processor in between or even
during user events.

Threads
Threads are the basic unit to which an operating system allocates processor
Delivery Tip time, and more than one thread can execute code inside a process. Each thread
You can quickly illustrate
how multiple threads are
maintains exception handlers, a scheduling priority, and a set of structures that
used to create nonblocking the system uses to save the thread context until it is scheduled. The thread
UI by running the Microsoft context includes all of the information that the thread needs to smoothly resume
Internet Explorer Web execution, including the thread’s set of CPU registers and stack, in the address
browser. Start the browser space of the thread’s host process.
and type a URL address or
click a link to a site that Operating systems use processes to separate the different applications that they
takes some time to are executing. The .NET Framework further subdivides an operating system
download. Show how you process into lightweight, managed subprocesses, called application domains,
can still interact with the represented by System.AppDomain. One or more managed threads,
application during this represented by System.Threading.Thread, can run in one or any number of
download operation, for application domains within the same process. A preemptive multitasking
example, canceling the operating system allocates a processor time slice to each thread that it executes.
current download by clicking Because each time slice is small, multiple threads appear to execute at the same
Stop.
time.
4 Module 14 (Optional): Threading and Asynchronous Programming

Advantages of using multiple threads

Threads enable multiple activities to appear to occur simultaneously in an
application. For example, a user can edit a worksheet while another thread
recalculates other parts of the worksheet within the same application. Threading
maintains the responsiveness of the user interface while background processing
is occurring. Threads can be used to enable users to receive notification of a
task’s progress, and even to cancel the task at any time.
You can also use threads to distinguish tasks of varying priority. For example,
you can use a high-priority thread to manage time-critical tasks, and a low-
priority thread to perform other tasks.
Threads are also useful when an application must wait for an event, such as user
input or a read from the network or from a file, before continuing to execute.
Multiple threads enable the processor to handle a separate task while waiting
for the completion of the event.

Potential disadvantages of using threads

In some circumstances, threading may cause application performance to
degrade. On a single-processor computer, a compute-bound task, such as
calculating a series of values by using multiple threads, would be slower
because of the overhead caused by thread-switching. Keeping track of a large
number of threads consumes significant processor time. If there are too many
threads, most of them will not make significant progress.
Controlling code execution with many threads is complex, and can be a source
of many bugs. You run the risk of data corruption or other problems, such as
deadlocks and race conditions. To protect an application’s data from possible
corruption, you must ensure that access to shared data is properly synchronized.
For more information about deadlocks and race conditions, see Thread Safety in
this module.

Note While this module focuses on threading, there are other ways of
achieving concurrency that include using multiple processes/AppDomains,
messaging, and database stored procedures.
Module 14 (Optional): Threading and Asynchronous Programming 5

Overview of Support for Threading in .NET

Topic Objective
To provide a high-level
overview of the
System.Threading ! Basic thread namespace
namespace and introduce
# System.Threading
the asynchronous design
pattern. ! Standard design pattern for asynchronous
Lead-in programming
Before examining how
threads work in the .NET # Hides thread creation and synchronization details
Framework, let’s briefly
review important ways in # Supported by .NET Framework delegate classes and/or
which the .NET Framework the IAsyncResult interface
provides support for
threading.

*ILLEGAL FOR NON-TRAINER USE**

To provide support for multithreaded programming, the .NET Framework
supplies its own namespace for thread creation and management and a
programming model to handle asynchronous operations.

Basic thread namespace

The System.Threading namespace provides classes and interfaces that enable
multithreaded programming. System.Threading includes classes that are used
to create and manage threads, protect shared data, and improve system
responsiveness.
The System.Threading.Thread class is an abstraction of a managed thread that
executes within the runtime. This includes threads that are created by the
runtime and those that are created outside the runtime but that interact with the
runtime environment to execute some managed code.
The System.Threading namespace includes classes that assist with thread
synchronization and protection of shared data. For example, the
System.Threading.Interlocked class provides atomic operations for variables
that are shared by multiple threads. The System.Threading.Monitor class
provides a synchronization mechanism to ensure that where multiple threads
access a shared resource, only one thread can access the resource at a particular
time.
6 Module 14 (Optional): Threading and Asynchronous Programming

Standard design pattern for asynchronous programming

The standard asynchronous design pattern in the .NET Framework provides an
efficient model to manage asynchronous operations and provide a consistent
programming model. The .NET Framework provides support for asynchronous
programming using the IAsyncResult interface and delegate classes that enable
a programmer to avoid some of the implementation details of threading. The
asynchronous design pattern is covered in more detail later in this module.
For more information about the System.Threading namespace and its classes,
see System.Threading Namespace in the .NET Framework SDK
documentation.
Module 14 (Optional): Threading and Asynchronous Programming 7

Thread Architecture in .NET

Topic Objective
To explain thread
architecture in .NET in terms
Example of a Process Hosting AppDomains
of application domains. AppDomain A AppDomain B
Lead-in
Let’s look at the different
Shared
SharedData
Data Shared
SharedData
Data
architectural components
that make up a single .NET
process.
Thread 1 Thread 2 Thread 3

Thread
Thread Thread
Thread Thread
Thread
Specific
Specific Specific
Specific Specific
Specific
Data
Data Data
Data Data
Data

*ILLEGAL FOR NON-TRAINER USE**

Application domains, also known as AppDomains, play a key role in how
threads work in the .NET Framework. An application domain is a runtime
representation of a logical process within a physical process. A single process
can contain multiple application domains, each of which is completely isolated
from other application domains within this or any other process. One or more
threads run in an application domain.
Although hosting threads within application domains is conceptually similar to
the COM threading model with its use of apartments, there is an important
difference: application domains are managed types whereas the COM threading
model is built on an unmanaged architecture.
For more information about application domains, see Module 2, “Introduction
to a Managed Execution Environment,” in Course 2349B, Programming with
the Microsoft .NET Framework (Microsoft Visual C# .NET).
8 Module 14 (Optional): Threading and Asynchronous Programming

Mapping from Win32 Threading to Managed Threading

The following table maps Microsoft Win32® threading elements to their
approximate runtime equivalent. Note that this mapping does not represent
identical functionality. For example, TerminateThread does not execute
finally clauses or free up resources, and cannot be prevented. However,
Thread.Abort executes all of your rollback code, reclaims all of the resources,
and can be denied by using ResetAbort. Be sure to read the .NET Framework
SDK closely before making assumptions about functionality.
In Win32 In the common language runtime

CreateThread Combination of new Thread() and

Thread.Start
TerminateThread Thread.Abort
SuspendThread Thread.Suspend
ResumeThread Thread.Resume
Sleep Thread.Sleep
WaitForSingleObject on the thread handle Thread.Join
ExitThread No equivalent
GetCurrentThread Thread.CurrentThread
SetThreadPriority Thread.Priority
No equivalent Thread.Name
No equivalent Thread.IsBackground
Close to CoInitializeEx (Ole32.dll) Thread.ApartmentState
Module 14 (Optional): Threading and Asynchronous Programming 9

" Using Threads in .NET

Topic Objective
To provide an overview of
the topics that you will cover
in this section. ! Starting Threads
Lead-in ! Thread Properties and Parameters
Having briefly reviewed how
an operating system uses ! Managing Threads
threads to perform
multitasking, let’s look at ! Thread Local Storage
how threading works in the
! Interrupting and Terminating Threads
.NET Framework.

*ILLEGAL FOR NON-TRAINER USE**

In this section you will learn how to start, manage, and terminate threads.
The System.Threading namespace includes classes for starting managing, and
terminating threads.
Being able to perform basic threading operations is only the first requirement in
creating multithreaded applications. On a more advanced level, you must
consider issues of data protection and performance. These issues are covered in
the topic Thread Safety in this module.
10 Module 14 (Optional): Threading and Asynchronous Programming

Starting Threads
Topic Objective
To explain how to instantiate
and start a new thread by ! Create a new instance of a Thread Object
using the .NET Framework
classes. # Constructor takes a ThreadStart delegate as its only
Lead-in parameter
Creating a new instance of a
Thread class creates a new
# ThreadStart references the method that will be
managed thread. executed by the new thread
! Thread is not executed until the Thread.Start method is
invoked
Thread
Thread tt == new
new
Thread(new
Thread(new ThreadStart(MyClass.AStaticMethod));
ThreadStart(MyClass.AStaticMethod));
t.Start();
t.Start();

*ILLEGAL FOR NON-TRAINER USE**

Creating a new instance of a Thread class creates a new managed thread. The
constructor for Thread takes, as its only parameter, a ThreadStart delegate
that references the method that will be executed by the new thread. The Thread
function does not begin executing until the Start method is called.
Module 14 (Optional): Threading and Asynchronous Programming 11

The following code shows how to create and start new threads:
using System;
using System.Threading;

class MyClass
{
//…
public static void AStaticMethod()
{
//…
}
public void AnInstanceMethod()
{
//…
}
}

class App
{

static void Main()

{
// Create and start thread on an instance method
MyClass aMyClass = new MyClass();
Thread t1 = new
Thread(new ThreadStart(aMyClass.AnInstanceMethod));
t1.Start();
// Create and start thread on a static method
Thread t2 = new
Thread(new ThreadStart(MyClass.AStaticMethod));
t2.Start();

//…
}
}

In the preceding example, the calls to t1.Start and t2.Start place the t1 and t2
threads in the running state, and the operating system can schedule them for
execution. The Start method submits an asynchronous request to the system,
and the call returns immediately, possibly before the new thread has started.
The thread’s execution begins at the first line of the method that is referred to
by the thread delegate. Calling Start more than once on the same thread causes
the runtime to throw a ThreadStateException.
12 Module 14 (Optional): Threading and Asynchronous Programming

Thread Properties and Parameters

Topic Objective
To describe some key
Thread class properties and ! Use the Thread.Name and Thread.Priority properties to
how to pass parameters to get or set the name and priority of the thread
threads.
Lead-in ! Designate a thread as a background or a foreground
To get or set the name of a thread by setting the Thread.IsBackground property
thread and its priority, use
the Thread.Name and # A background thread will not keep the managed
Thread.Priority properties. execution environment alive
t.Name
t.Name == "My
"My Background
Background Thread";
Thread";
t.Priority = ThreadPriority.AboveNormal;
t.Priority = ThreadPriority.AboveNormal;
t.IsBackground
t.IsBackground == true;
true;
! Encapsulate thread parameters in an object

*ILLEGAL FOR NON-TRAINER USE**

To get or set the name of a thread and its priority, use the Thread.Name and
Thread.Priority properties. Thread.Priority gets or sets the following values
that indicate the scheduling priority of a thread:
! Highest
! AboveNormal
! Normal
! BelowNormal
! Lowest

For example, to set the name of a thread t to “My Background Thread” and
make its priority AboveNormal, you use the following code:
t.Name = "My Background Thread";
t.Priority = ThreadPriority.AboveNormal;

Note Because the details of scheduling algorithms vary with each operating
system, operating systems are not required to honor the priority of a thread.
Module 14 (Optional): Threading and Asynchronous Programming 13

Background and Foreground Threads

A managed thread runs as a background thread or a foreground thread.
Background threads are identical to foreground threads except that a
background thread does not keep the managed execution environment alive.
After all foreground threads have been stopped in a managed process (where
the .exe file is a managed assembly), the system stops all background threads
and shuts down. You can designate a thread as a background or foreground
thread by setting the Thread.IsBackground property.
For example, to designate a thread as a background thread, you set
Thread.IsBackground to true. Likewise, to designate a thread as foreground
thread, set IsBackground to false.
All threads that enter the managed execution environment from unmanaged
code are marked as background threads. All threads that are generated by
creating and starting a new Thread object are foreground threads. If you create
a thread that you want to listen for some activity, such as a socket connection,
you should set Thread.IsBackground to true, so that your process can
terminate.
For example, to set a thread t to be a background thread:
t.IsBackground = true;
14 Module 14 (Optional): Threading and Asynchronous Programming

Encapsulating thread parameters in an object

It is sometimes important to supply parameters to a thread. However, the
ThreadStart delegate takes as its only parameter a ThreadStart delegate. The
following code demonstrates how to use an object to encapsulate thread
parameters:
using System;
using System.Threading;

class MyClassWithThreadState
{
int sleepTime;

public MyClassWithThreadState(int sleepTime)

{
this.sleepTime = sleepTime;
}

public void ThreadMethod()

{
// method can reference sleepTime
Thread.Sleep(sleepTime);
}
}

class Class1
{
static void Main()
{
int sleepTime = 1000; // time for the thread to sleep
MyClassWithThreadState myClassWithThreadState =
new MyClassWithThreadState(sleepTime);
Thread ts = new Thread(new
ThreadStart(myClassWithThreadState.ThreadMethod));
ts.Start();
// …
}
}
Module 14 (Optional): Threading and Asynchronous Programming 15

Managing Threads
Topic Objective
To describe the classes that ! Thread.Sleep causes the current thread to block
the runtime uses to pause,
resume, and force threads Thread.Sleep(3000);
Thread.Sleep(3000); //
// blocks
blocks for
for 33 seconds
seconds
to wait. ! Suspend and Resume methods are not generally useful
Lead-in # Can result in serious application problems like deadlocks
Let’s look at how the
runtime provides classes to ! Thread.Join waits for another thread to stop
manage threads.
t.Start();
t.Start();
t.Join();
t.Join(); //
// Wait
Wait for
for the
the thread
thread to
to exit
exit
! Thread.WaitHandle methods wait for one or more events
WaitHandle.WaitAll(waitEvents);
WaitHandle.WaitAll(waitEvents);
! Thread.ThreadState property - bit mask of the thread's state

*ILLEGAL FOR NON-TRAINER USE**

Typically, thread management includes tasks such as suspending a thread for a
period of time, waiting until another thread completes, or waiting until one or
more specific events occur.

Pausing and Resuming Threads

After starting a thread, you sometimes need to pause that thread for a fixed
period of time. Calling Thread.Sleep causes the current thread to immediately
block for the number of milliseconds you pass to Sleep, yielding the remainder
of its time slice to another thread. One thread cannot call Sleep on another
thread. For example, to cause the current thread to suspend for three seconds,
call the static method of Thread.Sleep as follows:
Thread.Sleep(3000);

Calling Thread.Sleep(Timeout.Infinite) causes a thread to sleep until it is

interrupted by another thread that calls Thread.Interrupt or is aborted by
Thread.Abort.

Using Thread.Suspend to pause a thread

You can also pause a thread by calling Thread.Suspend. When a thread calls
Thread.Suspend on itself, the call blocks until the thread is resumed by
another thread.
When one thread calls Thread.Suspend on another thread, the call is a
nonblocking call that causes the other thread to pause. Calling Thread.Resume
breaks another thread out of the suspended state and causes the thread to resume
execution, regardless of how many times Thread.Suspend was called. For
example, if you call Thread.Suspend five consecutive times and then call
Thread.Resume, the thread resumes execution immediately following the call
to Resume.
16 Module 14 (Optional): Threading and Asynchronous Programming

Unlike Thread.Sleep, Thread.Suspend does not cause a thread to immediately

stop execution. The runtime must wait until the thread has reached a safe point
before it can suspend the thread. A thread cannot be suspended if it has not been
started or if it has stopped.
For more information about safe points, see the .NET Framework SDK.
The Suspend and Resume methods are not generally useful for applications,
and you should not confuse them with synchronization mechanisms. Because
Suspend and Resume do not rely on the cooperation of the thread that is being
controlled, they are highly intrusive and can cause serious application problems.
For example, if you suspend a thread that holds a resource needed by another
thread, this causes a deadlock condition.
Some applications do need to control the priority of threads for better
performance. To do this, you should use Thread.Priority rather than
Thread.Suspend in your application.

Using Thread.Join to pause a thread

You can force a thread to wait for another thread to stop by calling
Thread.Join, as shown in the following code:
using System;
using System.Threading;

class MyApp
{//…
static void MyThreadMethod()
{
//…
}
static void Main()
{
// create, start and join a simple background thread
// MyThreadMethod is the secondary thread's entry point.
Thread t = new Thread(new ThreadStart(MyThreadMethod));
// Start the thread
t.Start();
// Wait for the thread to exit
t.Join();
}
}
Module 14 (Optional): Threading and Asynchronous Programming 17

Using the WaitHandle class to wait for events

You can force a thread to wait for one or more events to occur by calling
methods in the Thread.WaitHandle class.
The following table describes some of the methods in the WaitHandle class.
Method Description

WaitAll This method waits for all of the elements in the specified array to
receive a signal.
WaitAny This method waits for any of the elements in the specified array to
receive a signal.
WaitOne This method blocks the current thread until the current WaitHandle
receives a signal.

The WaitHandle class encapsulates Win32 synchronization handles. While

WaitHandle objects represent operating system synchronization objects and
expose advanced functionality, they are less portable than the Monitor.Wait
method, which is fully managed and, in some circumstances, is more efficient
in its use of operating system resources.

Using Classes that are derived from WaitHandle

Examples of classes that derive from WaitHandle include AutoResetEvent,
ManualResetEvent, and Mutex. You use the AutoResetEvent class to make a
thread wait until some event puts it in the signaled state by calling
AutoResetEvent.Set. Unlike ManualResetEvent, AutoResetEvent is
automatically reset to nonsignaled by the system after a single waiting thread
has been released. If no threads are waiting, the event object’s state remains
signaled. The AutoResetEvent corresponds to a Win32 CreateEvent call,
false specified by the bManualReset argument.
18 Module 14 (Optional): Threading and Asynchronous Programming

For example, the following code shows how to force the main thread to wait
until the threads that it has created signal that they have finished executing:
using System;
using System.Threading;

class MyClassWithThreadState
{
AutoResetEvent done;
public MyClassWithThreadState(AutoResetEvent done)
{
this.done = done;
}
public void ThreadMethod()
{
//…
done.Set(); // signal that we are finished
}
}

class MyApp
{
//…
static void Main()
{
//…
int numberOfThreads = 3; // number of threads to create
AutoResetEvent[] waitEvents = new
AutoResetEvent[numberOfThreads];
Thread ts;
MyClassWithThreadState myClassWithThreadState;
for (int i=0; i<numberOfThreads; i++)
{
waitEvents[i] = new AutoResetEvent(false);
myClassWithThreadState = new
MyClassWithThreadState(waitEvents[i]);
ts = new
Thread( new
ThreadStart(myClassWithThreadState.ThreadMethod));
ts.Start();
}
// Wait for all threads to indicate that they are done.
WaitHandle.WaitAll(waitEvents);
//…
}
}

Note You can also use multiple calls to the Thread.Join method to wait for
multiple threads to exit.

In this module, thread safety describes how to force a thread to wait for access
to a synchronized object, such as a Mutex method call.
Also in this module, Terminating Threads describes how to interrupt a waiting
thread by calling the Thread.Interrupt or Thread.Abort method.
Module 14 (Optional): Threading and Asynchronous Programming 19

Thread Activity States

The Thread.ThreadState property provides a bit mask that indicates a thread’s
current state. A thread is always in at least one of the possible states in the
ThreadState enumeration, and can be in multiple states at the same time.
When you create a managed thread, it is in the Unstarted state, and remains in
this state until it is moved into the started state by calling Thread.Start.
Unmanaged threads that enter the managed environment are already in the
started state.
When in the started state, some actions can cause the thread to change states.
The following table lists the actions that cause a change of state and the
corresponding new state.
Action ThreadState

A thread is created within the common language runtime. Unstarted

A thread calls Start. Running
The thread starts running. Running
The thread calls Sleep. WaitSleepJoin
The thread calls Wait on another object. WaitSleepJoin
The thread calls Join on another thread. WaitSleepJoin
Another thread calls Interrupt. Running
Another thread calls Suspend. SuspendRequested
The thread responds to a Suspend request. Suspended
Another thread calls Resume. Running
Another thread calls Abort. AbortRequested
The thread responds to an Abort request. Stopped
A thread is terminated. Stopped

Because the Running state has a value of 0, you cannot perform a bit test to
discover this state. Instead, you can use the following test (in pseudo-code):
if ((tState & (Unstarted | Stopped)) == 0) // implies Running

Threads are often in more than one state at any particular time. For example, if
a thread is blocked from a Wait call and another thread calls Abort on that
same thread, the thread is in both the WaitSleepJoin and the AbortRequested
state at the same time. In that case, as soon as the thread returns from the call to
Wait or is interrupted, it receives the ThreadAbortException.
After a thread leaves the Unstarted state as the result of a call to Thread.Start,
it can never return to the Unstarted state. A thread can never leave the Stopped
state, either.
20 Module 14 (Optional): Threading and Asynchronous Programming

Thread Local Storage

Topic Objective
To show how to use
managed thread local
storage. ! Managed thread local storage - data unique to a thread
Lead-in ! Thread-Relative Static Fields
Let’s discuss how to
manage thread local # Constructor code runs only on first thread, other thread’s
storage. thread static variables are initialized to null
class
class AClassWithThreadState
AClassWithThreadState
{{
[ThreadStatic]
[ThreadStatic] public
public static
static int
int count
count == 42;
42;

public
public void
void ThreadMethod()
ThreadMethod() {{
count++;
count++;
}}
}}

*ILLEGAL FOR NON-TRAINER USE**

Managed thread local storage (TLS) provides dynamic data slots that are unique
to a thread and an application domain combination. The two types of data slots
are named slots and unnamed slots. Named slots can be convenient, because
you can use a mnemonic identifier. But other components can intentionally or
unintentionally modify a named slot by using the same name for the
component’s own thread-relative storage. However, if you do not expose an
unnamed data slot to other code, it cannot be used by any other component.
To use managed TLS, create your data slot by using
Thread.AllocateNamedDataSlot or Thread.AllocateDataSlot, and use the
appropriate methods to set or retrieve the information that is placed there.
Module 14 (Optional): Threading and Asynchronous Programming 21

Thread-Relative Static Fields

If you know that a field of your type should always be unique to a thread and
application domain combination, decorate a static field with the
ThreadStaticAttribute attribute. Any class constructor code runs on the first
thread in the first context that accesses the field. In all other threads or contexts,
the field is initialized to null, or Nothing in Microsoft Visual Basic®.
Therefore, you should not rely on class constructors to initialize thread-relative
static fields. Instead, you should always assume that thread-relative static fields
are initialized to null.
For example, the following code shows how to use thread relative static fields
to store a thread specific counter:
class AClassWithThreadState
{
// NOTE: Only the first thread instance's field is
// initialized, other threads have the field zeroed
[ThreadStatic] public static int count = 42;

public void ThreadMethod()

{
count++;
// …
}
//…
}
22 Module 14 (Optional): Threading and Asynchronous Programming

Demonstration: Managing Threads

Topic Objective
To demonstrate how to
create and manage threads
in the .NET Framework.
Lead-in
In this demonstration, you
will see how to create and
manage threads in .NET, by
using some of the classes
and methods that we have
talked about in this section.

*ILLEGAL FOR NON-TRAINER USE**

This demonstration shows first how to create, manage, and join with a simple
Delivery Tip background thread. Then a more complex example is shown where parameters
You should run this demo
with breakpoints set in the
and thread static values for a thread instance are encapsulated in a class,
Main, MyThreadMethod, MyClassWithThreadState. After starting multiple threads, the main thread
and calls the WaitHandle.WaitAll method to wait until all those threads indicate
MyClassWithThreadState. that they have finished executing by setting their AutoResetEvent objects.
ThreadMethod methods
and observe the
Visual Studio .NET
The code for this demonstration is located in <install folder>\Democode\
Threads window.
Mod14\Demo14.1.
To make the Visual Studio
.NET Threads window
visible, when the application
is running, on the Debug
menu, click Windows, and
then click Threads.
Module 14 (Optional): Threading and Asynchronous Programming 23

Interrupting and Terminating Threads

Topic Objective
To explain how to terminate ! Thread.Interrupt method
a thread by using the .NET
Framework classes.
# Wakes a thread from any wait state and causes a
ThreadInterruptedException
Lead-in
Let’s look at how to ! Thread.Abort method to permanently terminate thread
terminate a thread in the
.NET Framework. # Wakes a thread from any wait state and causes a
ThreadAbortException
# ThreadAbortException is a special exception that can
be caught by application code, but is rethrown at the end
of the catch block unless ResetAbort is called
# Immediate abort not guaranteed, therefore use
Thread.Join to block until thread terminates

*ILLEGAL FOR NON-TRAINER USE**

In addition to starting, pausing, and resuming threads, the .NET Framework
also provides classes for terminating threads.
Thread.Interrupt wakes a thread from any wait state and causes a
ThreadInterruptedException to be thrown in the destination thread.
Thread.Abort is used to permanently terminate a thread.

Using Thread.Interrupt
When you call Thread.Interrupt, you wake a thread from any wait state and
cause a ThreadInterruptedException to be thrown in the destination thread.
The thread should catch the ThreadInterruptedException and do whatever is
appropriate to continue working. If the thread ignores the exception, the runtime
catches the exception and stops the thread.
For example, you may want to terminate a thread in response to a user-initiated
event, such as clicking a Cancel button. The Cancel button’s event handler may
run in one thread (thread1), while the event to which the Cancel action applies
may run in a separate thread (thread2). In your event handler, you can call the
Interrupt method on the second thread, as follows:
// inside the Cancel button's event handler
if ( thread2 != null)
{
thread2.Interrupt();
thread2 = null;
}
24 Module 14 (Optional): Threading and Asynchronous Programming

Using Thread.Abort
To terminate a thread permanently, you use the Thread.Abort method. When
you call Abort to terminate a thread, the system wakes the thread from any wait
state and throws a ThreadAbortException. The runtime executes the catch
block and any finally block.
ThreadAbortException is a special exception that can be caught by
application code, but is rethrown at the end of the catch block unless
ResetAbort is called. Only code with the proper permissions can call
ResetAbort method. ResetAbort cancels the request to abort, and prevents the
ThreadAbortException from terminating the thread. If the finally blocks
contain any unbounded computations, the thread’s termination may be delayed
indefinitely.
Because the call to Thread.Abort does not always result in the immediate
termination of a thread, you can ensure the thread’s destruction by calling the
Join method on the thread after you call Abort. Join blocks the calling thread
until the thread stops executing.
After a thread terminates, you cannot restart it by calling Start again. For
example, if code creates a thread, lets it run, and then aborts the thread, any
attempt to restart the thread causes the runtime to throw a
ThreadStateException.

Blocking Issues
If a thread makes an unmanaged call into the operating system, and the system
has blocked the thread in unmanaged code, the runtime will not take control of
the blocked thread for Thread.Interrupt or Thread.Abort.
In the case of Thread.Abort, the runtime marks the thread for Abort and takes
control of the thread when it re-enters managed code. Where possible, you
should use managed blocking rather than unmanaged blocking. The following
methods are all responsive to Thread.Interrupt and Thread.Abort:
! WaitHandle
! WaitOne
! WaitAny
! WaitAll
! Monitor.Enter
! Monitor.Block
! Thread.Join
! GC.WaitForPendingFinalizers

Also, if a thread is in a single-threaded apartment, all of these managed

blocking operations will correctly pump messages in the apartment while the
thread is blocked.
Module 14 (Optional): Threading and Asynchronous Programming 25

Demonstration: Interrupt and Abort

Topic Objective
To demonstrate how to
terminate threads by using
the Thread.Interrupt and
Thread.Abort methods.
Lead-in
In this demonstration, you
will see how to use the
Thread.Interrupt and
Thread.Abort methods to
terminate threads.

*ILLEGAL FOR NON-TRAINER USE**

This demonstration shows how to use Thread.Interrupt and Thread.Abort to
terminate threads.
Pay careful attention to what happens in the catch and finally blocks when the
Interrupt and Abort methods are called. Notice whether the thread resumes
working after the method calls as indicated by the output string “Thread - still
alive and working.”
26 Module 14 (Optional): Threading and Asynchronous Programming

The following code is used in the demonstration:

using System;
using System.Threading;

public class ThreadWork

{
static public bool resetAbort;

public static void DoWork()

{
try
{
for(int i=0; i<100; i++)
{
Console.WriteLine(
"Thread - working.");
Thread.Sleep(100);
}
}

catch(ThreadInterruptedException e)
{
Console.WriteLine(
"Thread - caught ThreadInterruptedException");
Console.WriteLine(
"Exception message: {0}", e.Message);
}

catch(ThreadAbortException e)
{
Console.WriteLine(
"Thread - caught ThreadAbortException");
Console.WriteLine(
"Exception message: {0}", e.Message);
if (resetAbort == true) Thread.ResetAbort();
}
finally
{
Console.WriteLine("Thread - finally block");
}
Console.WriteLine(
"Thread - still alive and working.");
Thread.Sleep(1000);
Console.WriteLine(
"Thread - finished working.");
}
}

(Code continued on the following page.)

Module 14 (Optional): Threading and Asynchronous Programming 27

class ThreadAbortTest
{
public static void Main()
{
ThreadStart myThreadDelegate = new
ThreadStart(ThreadWork.DoWork);
Thread myThread;

Console.WriteLine(
"Main - interrupting my thread.");
myThread = new Thread(myThreadDelegate);
myThread.Start();
Thread.Sleep(100);
myThread.Interrupt();
Thread.Sleep(2000);

ThreadWork.resetAbort = true;
Console.WriteLine(
"Main - aborting my thread with resetAbort: {0}.",
ThreadWork.resetAbort);
myThread = new Thread(myThreadDelegate);
myThread.Start();
Thread.Sleep(100);
myThread.Abort();
Thread.Sleep(2000);

ThreadWork.resetAbort = false;
Console.WriteLine(
"Main - aborting my thread with resetAbort: {0}.",
ThreadWork.resetAbort);
myThread = new Thread(myThreadDelegate);
myThread.Start();
Thread.Sleep(100);
myThread.Abort();
myThread.Join();
Console.WriteLine("Main ending.");
}
}
28 Module 14 (Optional): Threading and Asynchronous Programming

The output should be similar to the following:

Main - interrupting my thread.
Thread - working.
Thread - caught ThreadInterruptedException
Exception message: !
Thread has been interrupted from a waiting state.
Thread - finally block
Thread - still alive and working.
Thread - finished working.
Main - aborting my thread with resetAbort: True.
Thread - working.
Thread - caught ThreadAbortException
Exception message: Thread was being aborted.
Thread - finally block
Thread - still alive and working.
Thread - finished working.
Main - aborting my thread with resetAbort: False.
Thread - working.
Thread - caught ThreadAbortException
Exception message: Thread was being aborted.
Thread - finally block
Main ending.
Module 14 (Optional): Threading and Asynchronous Programming 29

" Thread Safety

Topic Objective
To provide an overview of
the topics that you will cover
in this section. ! Overview of Thread Safety
Lead-in ! Synchronization Context
In this section, we’ll look at
the importance of thread ! Synchronized Code Regions
safety and the mechanisms
that the .NET Framework ! Manual Synchronization
supports to provide thread
! Thread Safety and the .Net Framework Classes
safety.

*ILLEGAL FOR NON-TRAINER USE**

The System.Threading namespace provides classes and interfaces that enable
multithreaded programming. This namespace includes classes for synchronizing
access to data to provide thread safety.
This section focuses on the issues that you may encounter from sharing data
and resources between threads in multithreaded programming. The section also
introduces .NET Framework synchronization strategies.
30 Module 14 (Optional): Threading and Asynchronous Programming

Overview of Thread Safety

Topic Objective
To discuss problems that
result from sharing data and ! Common problems sharing data and resources between threads:
resources between threads, # Race condition – uncontrolled order of execution causing errors
and to introduce .NET
Framework synchronization # Deadlocks – threads waiting for each other so that they cannot
proceed
strategies.
! Best approach is to avoid sharing when possible
Lead-in
Let’s talk about how sharing # Encapsulate data into instances that are not shared across requests
data and resources between ! The .NET Framework provides three strategies to synchronize
threads can lead to access to instance and static methods and instance fields:
compromised thread safety.
# Synchronized contexts
# Synchronized code regions
# Manual synchronization

*ILLEGAL FOR NON-TRAINER USE**

When writing multithreaded applications, you may encounter common
problems, such as race conditions and deadlock.

Race condition
Two or more threads that simultaneously access the same data can cause
undesirable and unpredictable results. For example, one thread may update the
contents of a structure while another thread reads the contents of the same
structure. In this scenario, it is unknown what data the reading thread will
receive: the old data, the newly written data, or possibly a mixture of both.
When the proper operation of a program depends on the uncontrolled order of
execution of multiple threads, then a race condition exists.

Deadlock
A multithreaded application can also encounter problems with thread
synchronization if multiple threads are waiting for each other to release
resources. This blocking of thread execution is known as a deadlock.
For example, consider two threads that transfer money between accounts A and
B. The first thread, Thread 1, is coded to do the following tasks in the following
order:
! Wait for and acquire a lock on account A
! Wait for and acquire a lock on account B
! Transfer funds
! Release both locks

The second thread, Thread 2, is coded in the same way, except that it first
acquires a lock on account B, then on account A.
Module 14 (Optional): Threading and Asynchronous Programming 31

Consider the case where Thread 1 acquires lock A, but before it can acquire
lock B, Thread 2 runs and acquires lock B. In this case, both threads block
while waiting for the other lock. Because both threads are blocked, neither
thread releases the lock that is required by the other thread to proceed. This
condition is referred to as a deadlock situation.
You can best achieve thread safety by not sharing data or resources between
threads. If possible, use a design pattern that encapsulates data and resources
into instances that are not shared across requests. When this is not possible you
should use the .NET Framework thread synchronization classes to provide
thread safety.

.NET Framework strategies for synchronization

When you need to share data, the .NET Framework provides three strategies to
synchronize access to instance methods, static methods, and instance fields:
! Synchronized contexts
You can use the SynchronizationAttribute attribute to enable simple,
automatic synchronization for ContextBoundObject objects.
! Synchronized code regions
You can use the MethodImplAttribute class (passing
MethodImplOptions.Synchronized), the Monitor class, or compiler
support to synchronize only the code blocks that need it.
! Manual synchronization
You can use the various synchronization objects to create your own
synchronization mechanisms.

The runtime provides a thread model in which classes fall into a number of
categories that can be synchronized in a variety of different ways, depending on
the requirements.

No Synchronization
No synchronization support is the default for objects. Any thread can access
any method or field at any time.

Synchronized Context
You can use the SynchronizationAttribute on any class that is derived from
ContextBoundObject to synchronize all instance methods and fields. All
objects in the same context domain share the same lock. Multiple threads are
allowed to access the instance methods and fields, but only a single thread is
allowed at any one time. Static members are not protected from concurrent
access by multiple threads.
The following table shows the support provided for fields and methods under
the synchronization context category.
Synchronization context supports Synchronization context does not support

Instance fields and instance methods Global fields, static fields, and static methods
Specific code blocks
32 Module 14 (Optional): Threading and Asynchronous Programming

Synchronized Code Regions

You can use the Monitor class or a compiler keyword to synchronize blocks of
code, instance methods, and static methods. In Microsoft Visual C#™, the
keyword is lock. You can also decorate a method with a MethodImplAttribute
(passing MethodImplOptions.Synchronized), which has a similar result to
using Monitor or one of the compiler keywords for a Monitor code block
where the code block is the entire method.
The following table shows the support provided for fields and methods under
the synchronized code regions category.
Synchronized code regions supports Synchronized code regions does not
(only if marked) support

Static methods, instance methods, and Global fields, static fields, and instance
specific code blocks fields

Manual Synchronization
You can use the Interlocked, Mutex, ManualResetEvent, AutoResetEvent,
and ReaderWriterLock classes to acquire and release a lock to protect global,
static, and instance fields and global, static, and instance methods.
Module 14 (Optional): Threading and Asynchronous Programming 33

Synchronization Context
Topic Objective
To describe how to ! SynchronizationAttribute enables simple, automatic
synchronize access to synchronization for ContextBoundObject objects
instance fields and methods
by using synchronization # Only instance fields and methods are synchronized
contexts.
# Static fields and methods are not protected from
Lead-in concurrent access by multiple threads
Let’s look at using
synchronization contexts in [Synchronization()]
[Synchronization()]
more detail. class
class CounterSynchronizedContext
CounterSynchronizedContext :: ContextBoundObject
ContextBoundObject
{{
static
static int
int sCount
sCount == 0;
0; //multiple
//multiple threads
threads can
can access
access
int
int iCount
iCount == 0;
0; //only
//only one
one thread
thread can
can access
access at
at aa time
time

public
public void
void Increment()
Increment() {{
//…
//… only
only one
one thread
thread can
can access
access at
at aa time
time
}}
}}

*ILLEGAL FOR NON-TRAINER USE**

A context is an ordered sequence of properties that defines an environment for
the objects within it. Contexts are created during the activation process for
objects that are configured to require certain automatic services such as
synchronization. Multiple objects can reside inside a context.

Using the SynchronizationAttribute attribute

You can use the SynchronizationAttribute attribute to enable simple,
automatic synchronization for objects whose class derives from
ContextBoundObject. The attribute forces a synchronization domain for the
current context and all contexts that share the same instance. When you apply
this attribute to an object, only one thread can be executing in all contexts that
share an instance of this property. Multiple threads may access the methods and
fields, but only a single thread is allowed at any one time. Allowing only a
single thread at a time to access instance fields and methods may make these
fields and methods thread-safe.

Caution A synchronization context does not protect static fields and methods
from concurrent access by multiple threads.
34 Module 14 (Optional): Threading and Asynchronous Programming

For example, consider the CounterSynchronizedContext class. This class’s

instanceCount field and Increment method are protected from concurrent
access by multiple threads; only one thread at any one time can gain access to
these members. However, multiple threads may access its staticCount member,
as shown in the following code:
using System;
using System.Threading;
using System.Runtime.Remoting.Contexts;

[Synchronization()]
class CounterSynchronizedContext : ContextBoundObject
{
// Caution! multiple concurrent threads allowed for
// static field – can use manual synchronization to protect
static int staticCount = 0;

// only one thread at a time allowed for instance field

int instanceCount = 0;

// only one thread at a time can execute instance method

public void Increment()
{
Console.WriteLine(
"Start Object:{0} Thread:{1}!
Resource writing count, static:{2} instance:{3}",
this.GetHashCode(),
Thread.CurrentThread.GetHashCode(),
staticCount, instanceCount);
int tempStaticCount = staticCount;
int tempInstanceCount = instanceCount;
Thread.Sleep(50);
tempStaticCount++;
tempInstanceCount++;
staticCount = tempStaticCount;
instanceCount = tempInstanceCount;
Console.WriteLine(
"Stop Object:{0} Thread:{1}!
Resource writing count, static:{2} instance:{3}",
this.GetHashCode(),
Thread.CurrentThread.GetHashCode(),
staticCount, instanceCount);
}
}
Module 14 (Optional): Threading and Asynchronous Programming 35

Note There are two classes named SynchronizationAttribute: one in the

System.EnterpriseServices namespace, and the other in the
System.Runtime.Remoting.Contexts namespace. The
System.EnterpriseServices.SynchronizationAttribute class supports only
synchronous calls, and can be used only with serviced components. (For more
information about serviced components, see Serviced Component Overview in
the .NET Framework SDK documentation.) The
System.Runtime.Remoting.Contexts.SynchronizationAttribute supports
both synchronous and asynchronous calls, and can be used only with context
bound objects. This topic discusses only the
System.Runtime.Remoting.Contexts.SynchronizationAttribute.
36 Module 14 (Optional): Threading and Asynchronous Programming

Synchronized Code Regions

Topic Objective ! MethodImplAttribute with MethodImplOptions.Synchronized
To explain and contrast
different options for [MethodImplAttribute(MethodImplOptions.Synchronized)]
[MethodImplAttribute(MethodImplOptions.Synchronized)]
synchronizing blocks of # Method executed by only one thread at a time
code.
# Can be used to synchronize instance and static methods
Lead-in
In addition to synchronizing # Similar to using Monitor or Visual C# lock on the entire method
methods and fields, we also ! Monitor - synchronize access to a region of code
have several options for
synchronizing blocks of # Code region can be a portion of, or the entire method
code: # Monitor.Enter, Monitor.TryEnter, and Monitor.Exit
MethodImplAttribute, the
# C# lock keyword uses Monitor class methods
Monitor class, and the lock
keyword. lock(this) to protect instance, lock(typeof(class)) to protect static
lock
lock (typeof(Counter))
(typeof(Counter)) {{
//block
//block of
of protected
protected code
code
}}

*ILLEGAL FOR NON-TRAINER USE**

You can decorate a method with a MethodImplAttribute, passing
MethodImplOptions.Synchronized, which indicates that only one thread at a
time may execute the method. You can use this attribute to synchronize both
instance methods and static methods. Using this attribute provides the same
result essentially as using Monitor or the Visual C# lock keyword where the
synchronized code region encompasses the entire method.
Module 14 (Optional): Threading and Asynchronous Programming 37

[MethodImplAttribute(MethodImplOptions.Synchronized)]
In the following example, the class CounterSynchronizedCodeRegion has
both its instance method IncrementInstance and static method
IncrementStatic attributed for synchronized access. This allows only one
thread to execute either method at one time.
using System;
using System.Threading;
using System.Runtime.CompilerServices;

class ASynchronizedClassExample
{
static int staticValue = 0;
int instanceValue = 0;

[MethodImplAttribute(MethodImplOptions.Synchronized)]
public void ChangeInstance()
{
// thread safe changes to instanceValue
}

[MethodImplAttribute(MethodImplOptions.Synchronized)]
public static void ChangeStatic()
{
// thread safe changes to staticValue
}
}
//…

Note You can use Thread.Interrupt to break a thread out of blocking

operations, such as waiting for access to a synchronized region of code.

Monitor Class and the C# Compiler lock Keyword

Using the Monitor class or Visual C# lock keyword is a little more complex
than using MethodImplAttribute, but these approaches give you the flexibility
to synchronize access to a specific region of code and not just to the entire
method. By synchronizing the least amount of code required for thread safety,
you maximize the amount of possible concurrency.
The Monitor class supports the following code-block synchronization:
! Synchronized instance methods
On instance methods, the current object is used for synchronization.
Visual C# uses the this keyword to indicate the current object, while
Visual Basic .NET use the Me keyword.
! Synchronized static methods
On static methods, the class is used for synchronization.

The Monitor class provides methods that you can use to synchronize access to
a specific region of code by taking and releasing a lock on a particular object.
After you obtain a lock on a code region, you can use the Monitor.Wait,
Monitor.Pulse, and Monitor.PulseAll methods.
38 Module 14 (Optional): Threading and Asynchronous Programming

Monitor.Wait
The Monitor.Wait method releases the lock on an object and blocks the current
thread until it reacquires the lock. The thread that currently owns the lock on the
specified object invokes this method to release the object so that another thread
can access it. The caller is blocked while waiting to reacquire the lock. This
method is called when the calling thread is waiting for a change in the state of
the object that will occur as a result of another thread’s operations on the object.
When a thread calls Wait, it releases the lock on the object and enters the
object’s waiting queue. The next thread in the object’s ready queue, if there is
one, acquires the lock and has exclusive use of the object. All threads that call
Wait remain in the waiting queue until they receive a signal from Pulse or
PulseAll, sent by the owner of the lock. If Pulse is sent, only the thread at the
head of the waiting queue is affected. If PulseAll is sent, all threads that are
waiting for the object are affected. When the signal is received, one or more
threads leave the waiting queue and enter the ready queue. A thread in the ready
queue is permitted to reacquire the lock.
This method returns when the calling thread reacquires the lock on the object.
Note that this method blocks indefinitely if the holder of the lock does not call
Pulse or PulseAll.

Caution You should check whether the Pulse method is ever called before its
corresponding Wait method is called. A thread must have already issued a
Wait for the Pulse to affect it. You can use the Monitor.Wait methods with a
timeout parameter to prevent the caller of the Wait from blocking indefinitely
when such a condition occurs.

Monitor.Pulse
The Monitor.Pulse method notifies a thread in the waiting queue of a change in
the locked object's state. Only the current owner of the lock can signal a waiting
object by using Pulse. The thread that currently owns the lock on the specified
object invokes this method to signal the next thread in line for the lock. Upon
receiving the pulse, the waiting thread is moved to the ready queue. When the
thread that invoked Pulse releases the lock, the next thread in the ready queue,
which is not necessarily the thread that was pulsed, acquires the lock.

Note Be aware of the distinction between the use of Monitor and WaitHandle
objects. Monitor objects are purely managed, fully portable, and may be more
efficient in terms of operating system resource requirements. WaitHandle
objects represent operating system waitable objects, are useful for
synchronizing between managed and unmanaged code, and expose some
advanced operating system features like the ability to wait on many objects at
once.
Module 14 (Optional): Threading and Asynchronous Programming 39

Compiler Support
Both Visual Basic and Visual C# support a language keyword that uses
Monitor.Enter and Monitor.Exit to lock the object. Visual Basic supports the
SyncLock keyword; Visual C# supports the lock keyword.
When you use the lock or SyncLock keyword, the compiler generates code.
The Visual C# and Visual Basic compilers emit a try/finally block with
Monitor.Enter at the beginning of the try, and Monitor.Exit in the finally
block. If an exception is thrown inside of the lock or SyncLock block, the
finally handler runs to allow you to perform any clean-up work.
The C# statement, of the form lock(x) where x is an expression of a reference-
type, is equivalent to the following except that x is only evaluated once:
System.Threading.Monitor.Enter(x);
try {
...
}
finally {
System.Threading.Monitor.Exit(x);
}

The lock keyword marks a statement block as a critical section.

lock(expression) statement_block,
where expression specifies the object that you want to lock on. expression must
be a reference type.
Typically, expression is this if you want to protect an instance variable, or
typeof(class) if you want to protect a static variable or if the critical section
occurs in a static method in the specified class. The statement_block includes
the statements of the critical section.
40 Module 14 (Optional): Threading and Asynchronous Programming

For example, to synchronize access in a static method:

using System;
using System.Threading;

class Cache
{
public static void Add(object x)
{
// method code that doesn't require exclusive access
lock (typeof(Cache))
{
// code requiring exclusive access to static data
}
// method code that doesn't require exclusive access
}

public static void Remove(object x)

{
// method code that doesn't require exclusive access
lock (typeof(Cache))
{
// code requiring exclusive access to static data
}
// method code that doesn't require exclusive access
}
}

For example, to synchronize access in an instance method:

class Counter
{
public override int Read(int threadNum)
{
// ...
// method code that doesn't require exclusive access
lock(this)
{
// code requiring exclusive access to instance data
}
// method code that doesn't require exclusive access
}
//…
}
Module 14 (Optional): Threading and Asynchronous Programming 41

Demonstration: Using Synchronization Contexts and Synchronized

Code Regions to Provide Thread Safety
Topic Objective
To demonstrate the use of
synchronization contexts
and synchronized code
regions to provide thread
safety.
Lead-in
In this demonstration, you
will see how to achieve
thread safety by using
synchronization contexts
and synchronized code
regions.

*ILLEGAL FOR NON-TRAINER USE**

This demonstration shows the use of synchronization contexts and
synchronized code regions to provide thread safety. The demonstration consists
of several test sequences, which are described in this topic.
The code for this demonstration is located in <install folder>\Democode\
Mod14\Demo14.3.

The Unsafe test

The Unsafe test shows the race condition that occurs when multiple threads
concurrently execute a method on a class that is not thread-safe.
The CounterUnsafe class has a method that is named Increment, which reads
an object’s instance variable that is named count, increments its value, and
stores the value back in count. The class and its method do not synchronize
access. Therefore, the condition can arise where one thread executing the
method has read the value of count but before it can increment it and store it
back in count, another concurrently executing thread executing the same
method reads the same starting value as the first thread.
42 Module 14 (Optional): Threading and Asynchronous Programming

The Unsafe test should result in output that is similar to the following example.
Notice that the Increment method has been called three times but the count has
only been incremented by one.
Starting Unsafe Test
Start Resource writing count: 0
Start Resource writing count: 0
Start Resource writing count: 0
Stop Resource writing count: 1
Stop Resource writing count: 1
Stop Resource writing count: 1
All Unsafe threads have completed.

The Static Method Synchronized Context test

The Static Method Synchronized Context test calls the static IncrementStatic
method on the CounterSynchronizedContext class, which inherits from
ContextBoundObject and has a [Synchronization()] attribute.
Because synchronization contexts do not synchronize static methods, the
following undesirable result occurs:
Starting Static Method Synchronized Context Test
Start Thread:7 Resource writing count, static:0
Start Thread:8 Resource writing count, static:0
Start Thread:9 Resource writing count, static:0
Stop Thread:7 Resource writing count, static:1
Stop Thread:8 Resource writing count, static:1
Stop Thread:9 Resource writing count, static:1
All Static Method Synchronized Context threads have completed.

The Instance Method Synchronized Context test

The Instance Method Synchronized Context test calls the IncrementInstance
instance method on the CounterSynchronizedContext class, which inherits
from ContextBoundObject and has a [Synchronization()] attribute.
Because synchronization contexts do synchronize instance methods, the
following correct result occurs:
Starting Instance Method Synchronized Context Test
Start Object:39 Thread:31 Resource writing count, instance:0
Stop Object:39 Thread:31 Resource writing count, instance:1
Start Object:39 Thread:32 Resource writing count, instance:1
Stop Object:39 Thread:32 Resource writing count, instance:2
Start Object:39 Thread:33 Resource writing count, instance:2
Stop Object:39 Thread:33 Resource writing count, instance:3
All Instance Method Synchronized Context threads have!
completed.

Note Unlike a COM STA, a synchronized context is entered by many different

threads. Like a COM STA, only one thread at a time can execute the instance
methods.
Module 14 (Optional): Threading and Asynchronous Programming 43

The Static Method Synchronized Code Region test

The Static Method Synchronized Code Region test calls the
CounterSynchronizedCodeRegion class’s static method, IncrementStatic,
that has the [MethodImplAttribute(MethodImplOptions.Synchronized)]
attribute. Because synchronized code regions can be used to synchronize static
methods, the following correct result occurs:
Starting Static Method Synchronized Code Region Test
Start Thread:40 Resource writing count, static:0
Stop Thread:40 Resource writing count, static:1
Start Thread:41 Resource writing count, static:1
Stop Thread:41 Resource writing count, static:2
Start Thread:42 Resource writing count, static:2
Stop Thread:42 Resource writing count, static:3
All Static Method Synchronized Code Region threads have!
completed.

The Instance Method Synchronized Code Region test

The Instance Method Synchronized Code Region test calls the
CounterSynchronizedCodeRegion class’s instance method,
IncrementInstance, that has the
[MethodImplAttribute(MethodImplOptions.Synchronized)] attribute.
Because synchronized code regions can be used to synchronize instance
methods, the following correct result occurs:
Starting Instance Method Synchronized Code Region Test
Start Object:47 Thread:44 Resource writing count, instance:0
Stop Object:47 Thread:44 Resource writing count, instance:1
Start Object:47 Thread:45 Resource writing count, instance:1
Stop Object:47 Thread:45 Resource writing count, instance:2
Start Object:47 Thread:46 Resource writing count, instance:2
Stop Object:47 Thread:46 Resource writing count, instance:3
All Static Method Synchronized Code Region threads have!
completed.
44 Module 14 (Optional): Threading and Asynchronous Programming

Manual Synchronization
Topic Objective
To describe the use of the
Interlocked class methods, ! Interlocked methods – synchronize access to a variable
the Mutex class, and the that is shared by multiple threads
ReaderWriterLock class in
manual synchronization. # CompareExchange, Decrement, Exchange, Increment
Lead-in
Let’s look at some options
# Threads of different processes can use this mechanism
that the .NET Framework to safely handle variables in
provides to create shared memory
synchronization
mechanisms. ! Mutex – synchronization between threads
across processes
! ReaderWriterLock – single-writer/multiple-reader

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework provides several synchronization classes, which you can
use to create your own synchronization mechanisms. Manual synchronization
may be useful for the following operations:
! Synchronizing access to a variable that is shared by multiple threads
! Synchronizing between threads and across processes
! Defining a lock that implements single-writer/multiple-reader semantics

Using methods of the Interlocked class

The Interlocked class methods Increment, Decrement, Exchange, and
CompareExchange provide a simple mechanism for synchronizing access to a
variable that is shared by multiple threads. The threads of different processes
can use this mechanism if the variable is in shared memory.
On modern processors, the methods of the Interlocked class can often be
implemented by a single instruction. Thus, the methods of the Interlocked
class provide very high-performance synchronization, and can be used to build
higher-level synchronization mechanisms, like spin locks.
Module 14 (Optional): Threading and Asynchronous Programming 45

Increment and Decrement

The Increment and Decrement methods combine the operations of
incrementing or decrementing the variable and checking the resulting value.
This atomic operation is useful in a multitasking operating system, in which the
system can interrupt one thread’s execution to grant a slice of processor time to
another thread.
Without such synchronization, one thread can increment a variable but be
interrupted by the system before it can check the resulting value of the variable.
A second thread can then increment the same variable. When the first thread
receives its next time slice, it will check the value of the variable, which has
now been incremented not once, but twice. The Interlocked variable access
methods protect against this kind of error.

Note The C# increment operator (++) and decrement operator (--) are not
implemented by atomic operations and therefore do not provide the thread
safety that the Increment and Decrement methods do.

Exchange and CompareExchange

The Exchange method atomically exchanges the values of the specified
variables. The CompareExchange method combines two operations:
comparing the first and third parameter for equality, and if they are equal,
storing the second value in the first variable.
The Exchange and CompareExchange methods that are exposed by the
Interlocked class take arguments of type Object that can store references.
However, type safety requires that all of the arguments be typed strictly as
Object; you cannot simply cast an object to Object in the call to one of these
methods. Instead, you must create variables of type Object, assign a custom
object to that variable, and then pass that variable.
46 Module 14 (Optional): Threading and Asynchronous Programming

The following Visual C# code example only allows a single call to set the
property X. The property X is only set once because the CompareExchange
method changes the value of _x only when its first and third parameters are
equal, that is to say when _x is equal to null. After _x has been set to ovalue, it
no longer equals null and the CompareExchange method will no longer
modify it.
using System;
using System.Threading;

namespace CompareandExchange
{
class PropertyTest
{
private Object _x;
public int X
{
set {
Object ovalue = value;
Interlocked.CompareExchange(
ref _x, ovalue, null);
}
get {
return (int) _x;
}
}
}

class Class1
{
static void Main(string[] args)
{
PropertyTest pt = new PropertyTest();
pt.X = 1;
pt.X = 2;
Console.WriteLine("pt.X: {0}", pt.X);
}
}
}

This code outputs:

pt.X: 1
Module 14 (Optional): Threading and Asynchronous Programming 47

Mutex
You can use a Mutex object to synchronize between threads and across
processes. The Mutex class provides a synchronization primitive that grants
exclusive access to the shared resource to only one thread. If a thread acquires a
mutex, the second thread that wants to acquire that mutex is suspended until the
first thread releases the mutex. Although Mutex does not have all of the wait
and pulse functionality of the Monitor class, it does offer the creation of named
mutexes that can be used between processes.
You call WaitOne, WaitAll, or WaitAny to request ownership of the Mutex.
The state of the Mutex is signaled if no thread owns it.
If a thread owns a Mutex, that thread can specify the same Mutex in repeated
wait-request calls without blocking its execution. However, it must release the
Mutex as many times as it called wait to release ownership. If a thread
terminates normally while owning a Mutex, the state of the Mutex is set to
signaled and the next waiting thread gets ownership. The Mutex class
corresponds to a Win32 CreateMutex call.

ReaderWriterLock
The ReaderWriterLock defines a lock that implements single-writer/multiple-
reader semantics. In terms of resources, ReaderWriterLock objects are
sufficiently inexpensive enough to be used in large numbers such as with per-
object synchronization.
The ReaderWriterLock provides equity between readers and writers. After a
writer-lock is requested, no new readers are accepted until the writer has access.
Neither readers nor writers are perpetually denied access. The
ReaderWriterLock class supports functionality for upgrading to a writer lock
with a return argument that indicates intermediate writes, and for downgrading
from a writer lock, which restores the state of the lock. The class recovers from
most common failures such as the creation of events. The lock maintains a
consistent internal state and remains usable.
48 Module 14 (Optional): Threading and Asynchronous Programming

The following example shows how a class can use a ReaderWriterLock object
to allow multiple threads to execute its Read method or a single thread to
execute its Write method at any time.
using System;
using System.Threading;

class Resource
{
ReaderWriterLock rwl = new ReaderWriterLock();

public void Read(Int32 threadNum)

{
rwl.AcquireReaderLock(Timeout.Infinite);
try
{
// many can do read processing, writers blocked …
}
finally
{
rwl.ReleaseReaderLock();
}
}

public void Write(Int32 threadNum)

{
rwl.AcquireWriterLock(Timeout.Infinite);
try
{
// one can write processing, readers blocked …
}
finally
{
rwl.ReleaseWriterLock();
}
}
}
Module 14 (Optional): Threading and Asynchronous Programming 49

Thread Safety and the .Net Framework Classes

Topic Objective
To introduce .NET
Framework classes thread ! Public static members of .NET Framework classes are
safety issues. thread-safe – other public members see .NET SDK
Lead-in ! .NET Framework Collections classes, by default, are
Let’s look at the thread generally not thread-safe for modification
safety issues of the .NET
Framework classes. # Hashtable is thread safe for one writer and
multiple readers
! To obtain a thread-safe collection class
# Use or implement a thread-safe wrapper object obtained
from a Synchronized method
# Use a locking mechanism

*ILLEGAL FOR NON-TRAINER USE**

All public static members (methods, properties, and fields) within the .NET
Framework support concurrent access within a multithreaded environment.
Therefore, you can invoke any .NET Framework static member simultaneously
from two threads without encountering race conditions, deadlocks, or crashes.
To determine whether a .NET Framework class or structure is thread-safe, see
the Thread Safety section for that class or structure in the .NET Framework
SDK documentation.
If you want to use a nonthread-safe class in a multithreaded environment, you
must wrap an instance of the class with code that supplies the necessary
synchronization constructs.
50 Module 14 (Optional): Threading and Asynchronous Programming

Collections
By default, Collections classes are generally not thread-safe. Multiple readers
can safely read the collection; however, any modification to the collection
produces undefined results for all threads that access the collection, including
the reader threads.
You can make Collections classes thread safe by using any of the following
techniques:
! Create a thread-safe wrapper by using the Synchronized method and access
the collection exclusively through that wrapper. When implementing the
Synchronized method, derived classes must override the IsReadOnly
property to return the correct value.
! If the class does not have a Synchronized method, derive from the class and
implement a Synchronized method by using the SyncRoot property.
! Use a locking mechanism, such as the lock statement in Visual C#
(SyncLock in Visual Basic), on the SyncRoot property when accessing the
collection.

By default, only the Hashtable class guarantees thread safety when one writer
and multiple readers simultaneously access the collection. You can make the
collection thread-safe for multiple writers by using any of the preceding
techniques.
The Array class does not include a Synchronized method and, although it has
a SyncRoot property, you cannot derive from the class. Therefore, you can
make an array thread safe only through the locking mechanism.
Module 14 (Optional): Threading and Asynchronous Programming 51

" Special Thread Topics

Topic Objective
To provide an overview of
the topics that you will cover
in this section. ! Timer Class
Lead-in ! Thread Pools
Having looked at threading
in general and within the ! Threads and COM Interoperability
context of the .NET
Framework, let’s focus now ! Using Threads with Windows Forms Controls
on some specialized thread
! Best Practices for Working with Threads
topics.

*ILLEGAL FOR NON-TRAINER USE**

In addition to the basic thread creation and management operations and the
thread safety support through synchronization mechanisms, the .NET
Framework provides other interesting areas of threading functionality.
In this section, you will learn about timers and thread pools. The
System.Threading namespace includes:
! A Timer class that enables a delegate to be called after a specified amount
of time
! A ThreadPool class that manages groups of threads
! An IOCompletionCallback class to enable notification when an I/O
operation completes

You will also learn how the runtime synchronizes access to shared resources
between unmanaged COM objects and managed objects in a way that ensures
thread safety.
In addition, you will learn about the requirements for dealing with nonthread-
safe Windows Forms controls, and how you can optimize the performance
effects that are associated with marshaling method calls.
Finally, you will learn the recommended best practices for implementing
thread-safe code.
52 Module 14 (Optional): Threading and Asynchronous Programming

Timer Class
Topic Objective
To describe how to use the
Thread.Timer class with a
delegate to execute ! Thread.Timer class - periodically executes a method
methods periodically.
# Threading.TimerCallback delegate for callback method
Lead-in
The Thread.Timer class # Change method changes timer values
provides functionality to
execute a method at # Dispose method frees the resources held by the timer
specified intervals.
Timer
Timer timer
timer == new
new Timer(
Timer(
new
new TimerCallback(CheckStatus),
TimerCallback(CheckStatus), null,
null, 0,
0, 2000);
2000);
//
// ……
static
static void
void CheckStatus(Object
CheckStatus(Object state)
state) {{
Console.WriteLine("Checking
Console.WriteLine("Checking Status.");
Status.");
}}

*ILLEGAL FOR NON-TRAINER USE**

The Thread.Timer class provides a mechanism for executing methods at
specified intervals. You cannot inherit from this class.
To specify the methods associated with a Timer, use a TimerCallback
delegate. Specify the timer delegate when the timer is constructed. The timer
delegate cannot be changed. The method calls do not execute in the thread that
creates the timer; they execute in a separate thread that is automatically
allocated by the system.
When you create a timer, you specify an amount of time to wait before the first
invocation of the delegate method (due time), and an amount of time to wait
between subsequent invocations (period). A timer invokes its methods when its
due time elapses, and invokes its methods once per period thereafter. You can
change these values, or you can disable the timer, by using the Change method.
When a timer is no longer needed, use the Dispose method to free the resources
held by the timer.

Note There are multiple Timer classes in the .NET Framework. Be careful not
to confuse the Thread.Timer class with the System.Timers.Timer and
System.Windows.Forms.Timer classes. For more information about these
classes, see the .NET Framework SDK documentation.
Module 14 (Optional): Threading and Asynchronous Programming 53

The following example shows how to use a timer and a delegate to execute
methods at specified intervals of two seconds:
using System;
using System.Threading;

class App {
public static void Main() {
Console.WriteLine(
"Checking for status updates every 2 seconds.");
Console.WriteLine(
" (Hit Enter to terminate the sample)");
Timer timer = new Timer(new TimerCallback(CheckStatus),
null, 0, 2000);
Console.ReadLine();
timer.Dispose();
}

// The callback method's signature MUST

// match that of a System.Threading.TimerCallback
// delegate (it takes an Object parameter and returns void)
static void CheckStatus(Object state) {
Console.WriteLine("Checking Status.");
// ...
}
}
54 Module 14 (Optional): Threading and Asynchronous Programming

Thread Pools
Topic Objective
To introduce thread pooling.
! Thread pooling is used to improve efficiency
Lead-in
You can often use thread # System optimizes based on all of computer’s processes
pooling to make the use of ! Do not use thread pooling when you
multiple threads more
efficient. # Need a task to have a particular priority
# Have a task that might run for a long time
# Need to place threads into a single-threaded apartment
# Need a stable identity to be associated with the thread
! IOCompletionCallback delegate for asynchronous I/O
completion events
# A thread from the thread pool will process data when received

*ILLEGAL FOR NON-TRAINER USE**

You can often use thread pooling to make the use multiple threads more
efficient. Many applications use multiple threads, but often those threads spend
a great deal of time in the sleeping state waiting for an event to occur. Other
threads may enter a sleeping state and be awakened only periodically to poll for
a change or update status information before going to sleep again.

Advantages of thread pools

Using thread pooling provides your application with a pool of worker threads
that are managed by the system, allowing you to concentrate on application
tasks rather than thread management. In fact, if you have a number of short
tasks that require more than one thread, using the ThreadPool class is the
easiest and typically the most efficient way to take advantage of multiple
threads.
Thread pooling enables the system to optimize the use of multiple threads for
better throughput, not only for your application’s process but also with respect
to other processes on the computer. This optimization is transparent to your
application. When you use a thread pool, the system can optimize thread time
slices, taking into account all of the current processes on your computer.
Module 14 (Optional): Threading and Asynchronous Programming 55

Using thread pools in the .NET Framework

The .NET Framework uses thread pools for several purposes: asynchronous
calls, System.Net socket connections, asynchronous I/O completion, timers,
and registered wait operations, among others.
To use a thread pool, call ThreadPool.QueueUserWorkItem from managed
code, or CorQueueUserWorkItem from unmanaged code, and pass a
WaitCallback delegate that wraps the method that you want to add to the
queue.
You can also queue work items that need to be executed when a wait operation
completes. You queue these work items by using
ThreadPool.RegisterWaitForSingleObject and passing a WaitHandle and a
WaitOrTimerCallback delegate. When the WaitHandle is signaled or when
timed out, it raises a call to the method wrapped by the WaitOrTimerCallback
delegate. In both cases the thread pool uses or creates a background thread to
invoke the callback method.

Reasons Not to Use Thread Pools

There are several scenarios in which it is appropriate to create and manage your
own threads instead of using the ThreadPool class. You should do so when:
! You need a task to have a particular priority.
! You have a task that may run a long time and, therefore, block other tasks.
! You need to place threads into a single-threaded apartment (all ThreadPool
threads are in the multithreaded apartment).
! You need a stable identity to be associated with a particular thread. For
example, you may want to use a dedicated thread to abort that thread,
suspend it, or discover it by name.
56 Module 14 (Optional): Threading and Asynchronous Programming

The following example shows one way to use the ThreadPool class methods to
start multiple threads and monitor their completion:
using System;
using System.Threading;

class Counter
{
public void Read(int threadNum)
{
//…
}
public void Increment(int threadNum)
{
//…
}
}

class App
{
static Counter counter = null;
static int totalNumberOfAsyncOps = 10;
static int numAsyncOps = totalNumberOfAsyncOps;
static AutoResetEvent asyncOpsAreDone =
new AutoResetEvent(false);

public static void Main()

{
counter = new Counter();
for (int threadNum = 0;
threadNum < totalNumberOfAsyncOps;
threadNum++)
{
ThreadPool.QueueUserWorkItem(
new WaitCallback(UpdateResource), threadNum);
}
asyncOpsAreDone.WaitOne();
}
//…
// The callback method's signature MUST match that of a
// System.Threading.TimerCallback delegate
// (it takes an Object parameter and returns void)
static void UpdateResource(Object state)
{
int threadNum = (int) state;
if ((threadNum % 2) != 0) counter.Read(threadNum);
else counter.Increment(threadNum);

if (( Interlocked.Decrement(ref numAsyncOps)) == 0)
asyncOpsAreDone.Set();
}
}
Module 14 (Optional): Threading and Asynchronous Programming 57

IOCompletionCallback
Using asynchronous I/O completion events, a thread from the thread pool
processes data only when the data is received. After the data has been
processed, the thread returns to the thread pool.
To make an asynchronous I/O call, you must associate an operating system I/O
handle with the thread pool and specify a callback method. When the I/O
operation completes, a thread from the thread pool invokes the callback method.
For more information about using asynchronous I/O completion events, see the
.NET Framework SDK documentation.
58 Module 14 (Optional): Threading and Asynchronous Programming

Demonstration: Using Synchronization Techniques and Thread

Pooling
Topic Objective
To demonstrate various
synchronization techniques
and the use of the thread
pool.
Lead-in
In this demonstration, we’ll
look at various
synchronization techniques
and the use of the thread
pool.

*ILLEGAL FOR NON-TRAINER USE**

This demonstration shows how to perform synchronization using the C# lock
keyword and manual synchronization primitives and how to use the thread pool
to obtain multiple threads. The demonstration consists of several test sequences,
which are described in this topic.
The classes in the demonstration derive from the class Counter and differ by
the technique for synchronization that they implement. For each class’s test, the
even number threads execute the class’s Read method, which simply examines
and outputs the counter’s value, but does not modify it. The odd number threads
execute the class’s Write method, which reads the counter, increments the
value, and stores the new value back in the counter.
The code for this demonstration is located in <install folder>\Democode\
Mod14\Demo14.4.
Module 14 (Optional): Threading and Asynchronous Programming 59

The Unsafe test

The Unsafe test uses an instance of the CounterUnsafe class which does no
synchronization. As a result of the race condition, the five Write method
invocations fail to increase the value of count by 5.
The test results in output that is similar to the following:
Unsafe test:
Start Resource writing (Thread=0) count: 0
Start Resource reading (Thread=1)count: 0
Stop Resource reading (Thread=1) count: 0
Start Resource writing (Thread=2) count: 0
Start Resource reading (Thread=3)count: 0
Stop Resource writing (Thread=0) count: 1
Start Resource writing (Thread=4) count: 1
Stop Resource reading (Thread=3) count: 1
Start Resource reading (Thread=5)count: 1
Stop Resource reading (Thread=5) count: 1
Start Resource writing (Thread=6) count: 1
Start Resource reading (Thread=7)count: 1
Stop Resource reading (Thread=7) count: 1
Start Resource writing (Thread=8) count: 1
Stop Resource writing (Thread=2) count: 1
Start Resource reading (Thread=9)count: 1
Stop Resource reading (Thread=9) count: 1
Stop Resource writing (Thread=4) count: 2
Stop Resource writing (Thread=6) count: 2
Stop Resource writing (Thread=8) count: 2
All Unsafe threads have completed.
60 Module 14 (Optional): Threading and Asynchronous Programming

The Interlocked test

The Interlocked test uses an instance of the CounterUsingInterlocked class,
which uses an Interlocked.Increment instruction to atomically update the
count. The five Write method invocations now increment count by 5.
The test results in output that is similar to the following:
Interlocked test:
Start Resource writing (Thread=0) count: 0
Stop Resource writing (Thread=0) count: 1
Start Resource reading (Thread=1)count: 1
Start Resource writing (Thread=2) count: 1
Stop Resource writing (Thread=2) count: 2
Start Resource reading (Thread=5)count: 2
Start Resource reading (Thread=3)count: 2
Start Resource writing (Thread=4) count: 2
Stop Resource writing (Thread=4) count: 3
Start Resource writing (Thread=6) count: 3
Stop Resource writing (Thread=6) count: 4
Start Resource reading (Thread=7)count: 4
Start Resource writing (Thread=8) count: 4
Stop Resource writing (Thread=8) count: 5
Start Resource reading (Thread=9)count: 5
Stop Resource reading (Thread=1) count: 5
Stop Resource reading (Thread=5) count: 5
Stop Resource reading (Thread=3) count: 5
Stop Resource reading (Thread=7) count: 5
Stop Resource reading (Thread=9) count: 5
All Interlocked threads have completed.

Note In the preceding example, the Interlock.Increment method

synchronized the concurrent thread’s Write method updates the count.
However, this approach does not prevent the value of count from changing its
value during another thread’s execution of the Read method. The manual
synchronization techniques that are demonstrated in the remaining test
sequences will synchronize execution to provide a consistent value for count
during each Read operation.
Module 14 (Optional): Threading and Asynchronous Programming 61

The Lock test

The Lock test uses an instance of the CounterUsingLock class, which uses the
Visual C# lock keyword to synchronize access to the object so that only one
thread at a time executes either of the instance methods. The five Write method
invocations now increment count by 5, and all of the Read operations have a
consistent value for count.
The test results in output that is similar to the following:
Lock test:
Start Resource writing (Thread=0) count: 0
Stop Resource writing (Thread=0) count: 1
Start Resource writing (Thread=6) count: 1
Stop Resource writing (Thread=6) count: 2
Start Resource reading (Thread=9)count: 2
Stop Resource reading (Thread=9) count: 2
Start Resource reading (Thread=7)count: 2
Stop Resource reading (Thread=7) count: 2
Start Resource writing (Thread=4) count: 2
Stop Resource writing (Thread=4) count: 3
Start Resource writing (Thread=2) count: 3
Stop Resource writing (Thread=2) count: 4
Start Resource reading (Thread=3)count: 4
Stop Resource reading (Thread=3) count: 4
Start Resource reading (Thread=1)count: 4
Stop Resource reading (Thread=1) count: 4
Start Resource reading (Thread=5)count: 4
Stop Resource reading (Thread=5) count: 4
Start Resource writing (Thread=8) count: 4
Stop Resource writing (Thread=8) count: 5
All Lock threads have completed.
62 Module 14 (Optional): Threading and Asynchronous Programming

The Mutex test

The Mutex test uses an instance of the CounterUsingMutex class, with the
Mutex class to synchronize access to the object so that only one thread at a time
executes either of the instance methods. The five Write method calls now
increment count by 5, and all the Read operations have a consistent value for
count.
The test results in output that is similar to the following:
Mutex test:
Start Resource writing (Thread=0) count: 0
Stop Resource writing (Thread=0) count: 1
Start Resource reading (Thread=3)count: 1
Stop Resource reading (Thread=3) count: 1
Start Resource writing (Thread=4) count: 1
Stop Resource writing (Thread=4) count: 2
Start Resource reading (Thread=5)count: 2
Stop Resource reading (Thread=5) count: 2
Start Resource writing (Thread=6) count: 2
Stop Resource writing (Thread=6) count: 3
Start Resource reading (Thread=7)count: 3
Stop Resource reading (Thread=7) count: 3
Start Resource writing (Thread=8) count: 3
Stop Resource writing (Thread=8) count: 4
Start Resource writing (Thread=2) count: 4
Stop Resource writing (Thread=2) count: 5
Start Resource reading (Thread=1)count: 5
Stop Resource reading (Thread=1) count: 5
Start Resource reading (Thread=9)count: 5
Stop Resource reading (Thread=9) count: 5
All Mutex threads have completed.
Module 14 (Optional): Threading and Asynchronous Programming 63

The ReadWriteLock test

The ReadWriteLock test uses an instance of the
CounterUsingReaderWriterLock class, which uses the ReaderWriterLock
class to synchronize access to the object. Note that multiple readers or a single
writer can execute concurrently. The five Write method calls now increment
count by 5, and all of the Read operations have a consistent value for count.
Because a thread that is executing a Read does not block other threads that are
executing a Read, this technique enables the Read operations to complete
sooner than in the previous tests.
The test results in output that is similar to the following:
ReadWriteLock test:
Start Resource writing (Thread=0) count: 0
Stop Resource writing (Thread=0) count: 1
Start Resource reading (Thread=1)count: 1
Start Resource reading (Thread=3)count: 1
Start Resource reading (Thread=5)count: 1
Start Resource reading (Thread=7)count: 1
Start Resource reading (Thread=9)count: 1
Stop Resource reading (Thread=1) count: 1
Stop Resource reading (Thread=3) count: 1
Stop Resource reading (Thread=5) count: 1
Stop Resource reading (Thread=7) count: 1
Stop Resource reading (Thread=9) count: 1
Start Resource writing (Thread=2) count: 1
Stop Resource writing (Thread=2) count: 2
Start Resource writing (Thread=4) count: 2
Stop Resource writing (Thread=4) count: 3
Start Resource writing (Thread=6) count: 3
Stop Resource writing (Thread=6) count: 4
Start Resource writing (Thread=8) count: 4
Stop Resource writing (Thread=8) count: 5
All ReadWriteLock threads have completed.
64 Module 14 (Optional): Threading and Asynchronous Programming

Threads and COM Interoperability

Topic Objective
To explain how managed ! Thread calls to compatible COM apartment objects reduce costs
threads call into a COM # Calls go directly to the COM objects, costly proxy-stub is eliminated
component.
! A managed thread can indicate it will host an MTA or STA COM apartment
Lead-in using
COM components use # Thread.ApartmentState property or [STAThread] [MTAThread] attributes,
for example:
apartments to synchronize
access to resources. [STAThread]
[STAThread]
public
public static
static void
void Main(string[]
Main(string[] args)
args) {//…}
{//…}

! The finalizer thread and all ThreadPool threads are MTA

! Managed objects can be called from any COM apartment in a free-threaded
manner
# Except managed objects derived from ContextBoundObject
! Managed code calls out to COM objects following COM rules

*ILLEGAL FOR NON-TRAINER USE**

COM components use apartments to synchronize access to resources. In
contrast, managed objects use synchronized regions, synchronization primitives
such as mutexes, locks and completion ports, and synchronized contexts to
ensure that all shared resources are used in a thread-safe manner.

Calling a COM object from a managed thread

For interoperability, the runtime creates and initializes an apartment when a
managed thread creates a COM object. A managed thread can create and enter a
single-threaded apartment (STA) that contains only one thread, or a multi-
threaded apartment (MTA) that contains one or more threads. When a COM
apartment and a thread-generated apartment are compatible, COM allows the
calling thread to make calls directly to the COM object. If the apartments are
incompatible, COM creates a compatible apartment and marshals all calls
through a proxy in the new apartment.
On the first call to unmanaged code, the runtime calls CoInitializeEx to
initialize the COM apartment as an MTA or STA apartment. As long as the
proxy and stub are registered or the type library is registered, you do not have to
set this property.
Module 14 (Optional): Threading and Asynchronous Programming 65

Setting the Thread.ApartmentState property

You can mark a managed thread to indicate that it will host a single-threaded or
multithreaded apartment. The Thread.ApartmentState property returns and
assigns the apartment state of a thread. If the property has not been set, the
property returns ApartmentState.Unknown.
Whenever the COM object and the managed thread are in incompatible
apartments, all calls on the object are made through a COM-created proxy.
The following example shows how to create an STA apartment-threaded COM
object, AptSimple, from managed code:
using System.Threading;
using APTOBJLib;
//…
AptSimple obj = new AptSimple ();
obj.Counter = 1;

To eliminate the proxy and stub mechanism and significantly enhance

performance, set the ApartmentState on the thread before creating the object,
as follows:
using System.Threading;
using APTOBJLib;
//…
Thread.CurrentThread.ApartmentState = ApartmentState.STA;
AptSimple obj = new AptSimple ();
obj.Counter = 1;

You can set the ApartmentState property when the thread is in the
ThreadState.Unstarted or ThreadState.Running state; however, you can
only set the property once for a thread. The two valid property states are single-
threaded apartment (STA) or multithreaded apartment (MTA).
66 Module 14 (Optional): Threading and Asynchronous Programming

Using the [STAThread] and [MTAThread] attributes

In some situations, a thread may already have called into unmanaged code
before the ApartmentState could be set. As an alternative to setting the
ApartmentState enumeration, you can apply the
System.STAThreadAttribute or System.MTAThreadAttribute to the main
entry point of the application. By applying these attributes, you ensure that the
main thread of an application is in the proper state.
For example, to ensure that the main thread of a Windows Form is apartment
compatible with the Form’s control objects that must be created in a single
threaded COM apartment, you can use the following code:
//…
[STAThread]
public static void Main(string[] args)
{
//…
}

Other COM vs. managed threading issues

Either apartment state has little effect on the managed portion of your
application. The finalizer thread and all threads that are controlled by
ThreadPool are MTA.
Managed objects that are exposed to COM behave as if they had aggregated the
free-threaded marshaler. In other words, they can be called from any COM
apartment in a free-threaded manner. The only managed objects that do not
exhibit this free-threaded behavior are those objects that derive from the
ContextBoundObject class.
In the managed execution environment, there is no support for the
SynchronizationAttribute, unless you use contexts and context-bound
managed instances. If you are using EnterpriseServices, your object must
derive from ServicedComponent, which is itself derived from
ContextBoundObject.
When managed code calls out to COM objects, it always follows COM rules. In
other words, it calls through COM apartment proxies and COM+ 1.0 context
wrappers as dictated by OLE32.
Module 14 (Optional): Threading and Asynchronous Programming 67

Using Threads with Windows Forms Controls

Topic Objective ! Controls can only execute methods on the thread on
To describe how to use a which they are created
Windows Forms control’s
thread-safe method to make # Except for calls to their thread-safe methods
cross thread calls on the
control. ! Background thread calls to a control must be marshaled
Lead-in # Use thread-safe methods - Invoke, BeginInvoke, and
Because Windows Forms EndInvoke
controls can only execute on
the thread on which they are # Methods take a reference to a delegate, typically an
created, they are not instance of the MethodInvoker delegate
considered thread-safe.
! For example, a call to the aFormControl object’s
UpdateProgress method
MethodInvoker
MethodInvoker mi
mi == new
new
MethodInvoker(aFormControl.UpdateProgress);
MethodInvoker(aFormControl.UpdateProgress);
aFormControl.BeginInvoke(mi);
aFormControl.BeginInvoke(mi);

*ILLEGAL FOR NON-TRAINER USE**

Windows Forms controls can only execute on the thread on which they are
created. That is, they are not thread-safe. If you want to get or set properties, or
call methods, on a control from a background thread, you must marshal the call
to the thread that created the control.
There are five methods on a control that are safe to call from any thread:
InvokeRequired, Invoke, BeginInvoke, EndInvoke, and CreateGraphics.
For all other method calls on a control, you should pass a delegate to that
method as a parameter to the control’s Invoke or BeginInvoke methods. The
Invoke and BeginInvoke methods ensure that their delegate parameter’s
method is executed on the thread that owns this control’s underlying window
handle.
68 Module 14 (Optional): Threading and Asynchronous Programming

The following table describes the invoke methods and specifies the method
signatures for those methods.
Method Signature and description
InvokeRequired public bool InvokeRequired { get ; }

Returns true if the caller must call Invoke when making method
calls to this control.
BeginInvoke public IAsyncResult BeginInvoke(Delegate
method)
public IAsyncResult BeginInvoke(Delegate
method, Object[] args)

Executes the specified delegate on the thread that owns this

control’s underlying window handle. The delegate is called
asynchronously, and this method returns immediately. You can
call this method from any thread, even the thread that owns the
control’s handle. If the control’s handle does not exist yet, this
method will follow up the control’s parent chain until it finds a
control or form that has a window handle. If no appropriate
handle can be found, BeginInvoke throws an exception.
Exceptions within the delegate method are considered
untrapped and are sent to the application’s untrapped exception
handler.
EndInvoke public Object EndInvoke(IAsyncResult
asyncResult)

Retrieves the return value of the asynchronous operation

represented by the IAsyncResult interface that is passed. If the
asynchronous operation has not completed, this method blocks
until the result is available.
Invoke public Object Invoke(Delegate method)
public Object Invoke(Delegate method,
Object[] args)

Executes the specified delegate on the thread that owns this

control’s underlying window handle. The delegate is called
synchronously and this method returns after the invoked
method has returned. The return value is the result of the
invoked method. It is an error to call this method on the same
thread to which the control belongs.

The following code demonstrates how to create a background thread that uses a
MethodInvoker to update a ProgressBar control at regular intervals:
Module 14 (Optional): Threading and Asynchronous Programming 69

//…
//Start the background thread
timerThread = new Thread(new ThreadStart(ThreadProc));
timerThread.IsBackground = true;
timerThread.Start();

//…

//This function is executed on a background thread –

// it marshalls calls to update the UI back to
// the foreground thread
public void ThreadProc() {

try {
MethodInvoker mi = new
MethodInvoker(this.UpdateProgress);
while (true)
{
//Call BeginInvoke on the Form
this.BeginInvoke(mi);
Thread.Sleep(500) ;
}
}
//Thrown when the thread is interupted by the main
// thread - exiting the loop
catch (ThreadInterruptedException e)
{
//Simply exit....
}
catch (Exception we)
{
}
}

//This function is called from the background thread

private void UpdateProgress()
{
//Reset to start if required
if (progressBar1.Value == progressBar1.Maximum)
{
progressBar1.Value = progressBar1.Minimum ;
}
progressBar1.PerformStep() ;
}

//…

//Make sure to clean up the background thread in Dispose

public override void Dispose()
{
if (timerThread != null)
{
timerThread.Interrupt();
timerThread = null;
}
}
70 Module 14 (Optional): Threading and Asynchronous Programming

Note If you are making multiple cross-thread calls to a control, it is much more
efficient to create a new method that executes those calls and make a single
cross-thread call to the new method.
Module 14 (Optional): Threading and Asynchronous Programming 71

Demonstration: Windows Forms Threading

Topic Objective
To demonstrate how to use
a background thread in a
Windows Forms application.
Lead-in
In this demonstration, you
will see how to use a
background thread in a
Windows Forms application.

*ILLEGAL FOR NON-TRAINER USE**

This demonstration shows how to use a background thread in a Windows Form
application. The background thread will periodically advance the Windows
Form progress bar.
The code for this demonstration is located in <install folder>\Democode\
Mod14\Demo14.5.
You should run this demonstration with breakpoints set on the ThreadProc
method’s statement:
this.BeginInvoke(mi);

and on the UpdateProgress method’s statement:

progressBar1.PerformStep();

Start the application and observe the Microsoft Visual Studio® .NET Threads
window.

Note To make the Visual Studio .NET Threads window visible, while the
application is running, on the Debug menu, click Windows, and click Threads.

Click the form’s Start button, and when the program breaks, note the active
thread. Continue to the next breakpoint and again note the active thread. You
should observe that the BeginInvoke method marshaled the call to the
Windows Forms main thread.
72 Module 14 (Optional): Threading and Asynchronous Programming

Best Practices for Working with Threads

Topic Objective
To provide a brief review of
guidelines for working with ! Avoid providing static methods that alter static state
threads.
! Static state must be thread safe
Lead-in
If you need to implement ! Instance state does not need to be thread safe
threading in your
applications, there are some ! Avoid taking locks whenever possible
guidelines and best
practices of which you
! Be aware that deadlocks can result from calls in locked
should be aware.
sections
! Use the System.Threading.Interlocked classes in
preference to the lock statement where possible
! Avoid the need for synchronization if possible

*ILLEGAL FOR NON-TRAINER USE**

Use the following best practices and rules as design guidelines for
implementing threading in your applications:
! Avoid providing static methods that alter static state.
In common server scenarios, static state is shared across requests, which
means that multiple threads can execute requests that access the same static
state at the same time. This creates the potential for threading bugs.
Consider using a design pattern that encapsulates data into instances that are
not shared across requests.
! Static state must be thread-safe.
! Instance state does not need to be thread safe.
By default, a library is not thread safe. Adding locks to create thread-safe
code decreases performance, increases lock contention, and creates the
possibility for deadlock bugs to occur.
In common application models, only one thread at a time executes user
code, which minimizes the need for thread safety. For this reason, the .NET
Framework is not thread safe by default. In cases where you want to provide
a thread-safe version of a class, use a GetSynchronized method to return a
thread-safe instance of a type. For examples, see the System.Collections
namespace in the .NET Framework SDK documentation.
! Design your library with consideration for the efficiency costs of running in
a server scenario. Avoid taking locks whenever possible.
! Be aware of method calls in locked sections.
Deadlocks can result when a static method in class A calls static methods in
class B and vice versa. If A and B both synchronize their static methods,
this will cause a deadlock. You may discover this deadlock only under
heavy threading stress.
Module 14 (Optional): Threading and Asynchronous Programming 73

! Performance issues can result when a static method in a class calls a static
method in the same class.
If these methods are not factored correctly, performance will suffer because
there will be a large amount of redundant synchronization. Excessive use of
synchronization may negatively affect performance. In addition, it may have
a significant negative effect on scalability.
! Be aware of issues with the lock statement (SyncLock in Visual Basic).
It is tempting to use the lock statement to solve all threading problems.
However, the System.Threading.Interlocked class is superior for updates
that must be made automatically. It executes a single lock prefix if there is
no contention.
In a code review, you should look for instances like the one shown in the
following example.
lock(this)
{
myField++;
}

! Avoid the need for synchronization if possible.

For high traffic pathways, it is best to avoid synchronization. Sometimes
you can adjust the algorithm to tolerate race conditions rather than eliminate
them.
74 Module 14 (Optional): Threading and Asynchronous Programming

" Asynchronous Programming in .NET

Topic Objective
To provide an overview of
the topics that you will cover
in this section. ! Support for Asynchronous Programming in .NET
Lead-in ! Design Pattern for Asynchronous Programming
In this section, we will look
at how the .NET Framework ! Asynchronous File Stream Read Example
enables asynchronous
programming. ! Asynchronous Delegates

*ILLEGAL FOR NON-TRAINER USE**

The central idea behind asynchronous programming is to be able to issue
method calls to other components and to carry on with other work, without
waiting for the operation to complete. The runtime provides rich support for
asynchronous programming and handles the details of threading and data
exchange.
In this section, you will learn about how the .NET Framework supports
asynchronous programming.
Module 14 (Optional): Threading and Asynchronous Programming 75

Support for Asynchronous Programming in .NET

Topic Objective
To provide a high level
overview of the .NET
Framework support for ! Supported in Many Areas of .NET
asynchronous programming.
# I/O, sockets, networking, remoting, ASP.NET and Web
Lead-in Services, messaging (MSMQ), delegates
In addition to support for
asynchronous programming ! Offers a design pattern for asynchronous programming
in many areas of .NET, the
.NET Framework offers an # Consistent and type-safe programming model
asynchronous programming
design pattern. # User-created classes should conform to this
design pattern

*ILLEGAL FOR NON-TRAINER USE**

With asynchronous programming in the .NET Framework, you make a call to a
.NET Framework class method while the program continues execution until a
specified callback is made. If no callback is specified, the program continues
execution until it encounters blocking, polling, or waiting for the call to
complete.
For example, a program can call a method which enumerates a large list, while
the main program continues to execute. When the enumeration is complete, a
callback is made and the program addresses it.
Many areas of the .NET Framework support asynchronous programming,
including:
! File IO, Stream IO, Socket IO
! Networking: HTTP, TCP
! Remoting channels (HTTP, TCP) and proxies
! XML Web services created by using ASP.NET
! ASP.NET Web Forms
! Messaging message queues over MSMQ
! Asynchronous delegates

The .NET Framework provides a design pattern that makes asynchronous calls
uniform across the different parts of the framework. This pattern is very useful
for making complex calls that take a considerable amount of time to complete.
User-created classes that support asynchronous calls should conform to this
design pattern.
76 Module 14 (Optional): Threading and Asynchronous Programming

Design Pattern for Asynchronous Programming

Topic Objective
To provide details of the
! Caller decides whether to make a synchronous or asynchronous call
asynchronous design
pattern. # Server may explicitly implement asynchronous methods, or client can use
delegate object’s asynchronous support
Lead-in ! Caller does asynchronous operation in two parts
One of the innovations that
# Call begin method to supply parameters and start operation
is provided by the
- an object implementing IAsyncResult is returned
asynchronous design
pattern is that the caller can # When operation is done, call end method to obtain the results
decide whether a particular ! Caller has several options to know when operation is done
call should be # Callback method - if specified in the begin method call, callback is invoked
asynchronous. # Poll – check IAsyncResult.IsCompleted property
# Call end method – if called before operation is done, automatically waits
# Wait – wait on IAsyncResult.WaitHandle property, can use timeouts

*ILLEGAL FOR NON-TRAINER USE**

One of the innovations that is provided by the asynchronous design pattern is
that the caller can decide whether a particular call should be asynchronous. You
do not need to do additional programming for the called object for it to support
asynchronous client calls. The client can make an asynchronous call on another
object whose class does not explicitly support such calls by instantiating a
delegate object that refers to the object’s method.
The runtime and language compilers encapsulate methods that provide
asynchronous operation into delegate classes. The called object can choose to
explicitly support asynchronous behavior; either because it can implement
asynchronous behavior more efficiently than by using a general architecture, or
because the called object is designed to support only asynchronous behavior by
its callers. The level of asynchronous support of the called object is up to the
object’s author.
However, if an object is to explicitly support asynchronous methods, you
should follow the asynchronous design pattern for exposing these methods.

Details of the asynchronous design pattern

In the .NET Framework asynchronous design pattern, the asynchronous
operation is split into two logical parts: the part where the client calls a begin
operation method and provides input to start the asynchronous operation, and
the part where the results of the asynchronous operation are obtained by the
client through a call to an end operation method.
Module 14 (Optional): Threading and Asynchronous Programming 77

Beginning the asynchronous operation

In the first part of an asynchronous call, the caller upon invoking the begin
operation method can also supply an optional AsyncCallback delegate, in
addition to providing the input needed for the operation. This delegate refers to
the method to be called when the asynchronous operation is completed. The
begin method synchronously returns an object that implements the
IAsyncResult interface. The caller can use the methods of this interface to
determine the status of the asynchronous operation. The server typically
maintains any state that is associated with an asynchronous operation in this
waitable object.
The IAsyncResult interface specifies the properties that are listed in the
following table.
IAsyncResult interface property Description

AsyncState AsyncState returns the object that was provided as

the last parameter, as part of the begin operation
method call.
AsyncWaitHandle The AsyncWaitHandle property returns the
WaitHandle that is set after the server has
completed processing of the call.
CompletedSynchronously The CompletedSynchronously property is set to
true if the begin operation call completes
synchronously.
IsCompleted The IsCompleted property is set to true after the
server completes processing of the call.

Obtaining the results of the asynchronous operation

In the second part of an asynchronous call, the caller obtains the results of the
operation in one of the four following ways:
! Callback Method
If the caller supplied the optional AsyncCallback delegate, the callback
method referred to by this delegate will be called when the operation
completes.
! Polling
The caller can poll the returned IAsyncResult interface’s IsCompleted
property to determine if the call has completed.
! End Operation Method
The caller can attempt to complete the operation by calling the end
operation method, thereby blocking until the operation completes.
! WaitHandle, End Operation Method
The caller can wait on the IAsyncResult interface’s WaitHandle property.
One difference between this and the previous option is that the client can
use time outs to wake up periodically. Another difference is that the caller
can choose to wait for multiple events to occur by calling the WaitAll
method in the Thread.WaitHandle class and specifying an array of events,
see the topic, Using the WaitHandle class to wait for events in this module.
78 Module 14 (Optional): Threading and Asynchronous Programming

Note Cancel is not provided on IAsyncResult, because in many

implementations, there is no guarantee that an asynchronous operation will be
canceled.

Exceptions
If the begin operation method throws an exception, the caller can assume that
an asynchronous operation was not started and that the callback delegate will
not be called.
After an asynchronous operation starts, the client is notified of any exceptions
that are raised by the server when the client calls the end operation method.
Module 14 (Optional): Threading and Asynchronous Programming 79

Asynchronous File Stream Read Example

Topic Objective
To show the first part of the
Asynchronous File Stream ! Asynchronous read with callback
Read example by explaining
how to do an asynchronous # Create callback method delegate
read using a callback.
AsyncCallback
AsyncCallback myCallback
myCallback == new
new
Lead-in AsyncCallback(this.OnReadDone);
AsyncCallback(this.OnReadDone);
Let’s first look at how to do
an asynchronous read by
using a callback.
# Begin the operation
IAsyncResult
IAsyncResult ar
ar == aStream.BeginRead(buffer,0,
aStream.BeginRead(buffer,0,
buffer.Length,
buffer.Length, myCallback,(object)myState);
myCallback,(object)myState);

# In the callback method, complete the operations

int
int byteCount
byteCount == aStream.EndRead(ar);
aStream.EndRead(ar); //data
//data in
in buffer
buffer

*ILLEGAL FOR NON-TRAINER USE**

The examples in this topic show how to implement a client that uses the
System.IO.Stream class’s methods to read a sequence of bytes from a file. The
System.IO.Stream class’s synchronous read method is named Read and the
asynchronous methods are named BeginRead and EndRead.
For the complete running code of these examples, see <install folder>\
Democode\Mod14\Demo14.6.
The following code uses a byte array named buffer to store the bytes returned
from the read operation:
byte[] buffer = new byte [512];
string filename = "test.txt"
Stream aStream = File.OpenRead(filename);

The following code uses a synchronized call to read data from the file:
int byteCount = aStream.Read(buffer, 0, buffer.Length);
aStream.Close();

Details of the asynchronous read operation

The asynchronous operation consists of two logical parts: the part that takes
input from the client and calls the asynchronous operation, and the part that
supplies results of the asynchronous operation to the client.
80 Module 14 (Optional): Threading and Asynchronous Programming

Asynchronous Read With Callback

In this example the callback method is an instance method named
OnReadDone, which returns void and takes a single parameter of type
IAsyncResult. The System namespace defines a delegate class AsyncCallback
that matches the signature for the instance method so that there is no need to
declare a new delegate type.
You create the callback delegate object as follows:
AsyncCallback myCallback = new AsyncCallback(this.OnReadDone);

If the caller may issue multiple asynchronous calls, the caller must be able to
correlate each of the results to the original call. You can use the state parameter
of the method that makes the asynchronous call to store this information.
In this example, you store the name of the file being read in an instance of
MyState:
class MyState
{
public string filename;
public MyState(string filename) {
this.filename = filename;
}
}
// ...
MyState myState = new MyState(filename);

You can now make the asynchronous call as follows:

IAsyncResult ar = aStream.BeginRead(
buffer, 0, buffer.Length, myCallback, (object)myState);
// continue to execute

The BeginRead method returns and the thread can continue to execute while
the read operation proceeds. When the read operation completes, the
OnReadDone method is called, possibly on a separate thread. This method
performs the second part of the asynchronous operation, obtaining the results of
the operation as follows:
int byteCount = aStream.EndRead(ar); // data now in buffer
Console.WriteLine("Filename read: {0},
((MyState)(ar.AsyncState)).filename);
aStream.Close();

The next topic, Asynchronous File Stream Read Example (Continued),

completes the example, by showing how to do an asynchronous read with
polling.
Module 14 (Optional): Threading and Asynchronous Programming 81

Asynchronous File Stream Read Example (continued)

Topic Objective
To continue the
Asynchronous File Stream
Read example by explaining ! Asynchonous read with polling
how to do an asynchronous
# Begin the operation
read with polling.
Lead-in IAsyncResult
IAsyncResult ar
ar == aStream.BeginRead(buffer,0,
aStream.BeginRead(buffer,0,
Now let’s see how to do an buffer.Length,
buffer.Length, null,(object)myState);
null,(object)myState);
asynchronous read with
polling.
# Poll and complete
while
while (!ar.IsCompleted){
(!ar.IsCompleted){ //
// do
do whatever
whatever
}}
int
int byteCount
byteCount == aStream.EndRead(ar);
aStream.EndRead(ar); //
// data
data in
in buffer
buffer

*ILLEGAL FOR NON-TRAINER USE**

The preceding topic showed how to complete an asynchronous read operation
by using a callback delegate. In this topic, you will see how to obtain results of
the asynchronous read with polling.

Asynchronous Read with Polling

To handle the second part of the asynchronous operation by polling for
completion rather than using a callback method, you make the initial
asynchronous call by supplying a null value for the callback method.
IAsyncResult ar = aStream.BeginRead(
buffer, 0, buffer.Length,null, (object)myState);

The BeginRead method returns and the thread can continue to execute while
the read operation proceeds. In this case, the thread periodically polls the
IsCompleted property of the IAsyncResult to determine when the read
operation is complete.
while (!ar.IsCompleted)
{
// do whatever
}
int byteCount = aStream.EndRead(ar); // data now in buffer
Console.WriteLine("Filename read: {0},
((MyState)(ar.AsyncState)).filename);
aStream.Close();
82 Module 14 (Optional): Threading and Asynchronous Programming

Demonstration: Asynchronous File Stream Read

Topic Objective
To demonstrate how to use
synchronous and
asynchronous read methods
on a file stream.
Lead-in
In this demonstration, you
will see how to use
synchronous and
asynchronous read methods
on a file stream.

*ILLEGAL FOR NON-TRAINER USE**

This demonstration shows how to use synchronous and asynchronous read
methods on a file stream. For the asynchronous case, the four different ways to
complete the operation are shown: callback, poll, end method call, and wait
with timeout.
Notice that in the asynchronous case that uses a callback method, the callback
method may be executed on a different thread than the main code.
The code for this demonstration is located in <install folder>\Democode\
Mod14\Demo14.6.
Module 14 (Optional): Threading and Asynchronous Programming 83

The output that is produced by running the code is similar to the following:
Doing Synchronous Read

Synchronous Read Data:!

0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
01234567890123456789012345678901

Doing Callback Asynchronous Read

Asynchronous Callback Read

Filename: test.txt Data:!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
0123456789012345678901234567890123456789!
01234567890123456789012345678901

Doing Poll Asynchronous Read

Asynchronous Poll Read

(Code continued on the following page.)

84 Module 14 (Optional): Threading and Asynchronous Programming

Doing End Method Asynchronous Read

Asynchronous End Read

Doing Wait Asynchronous Read

Asynchronous Wait Read

Asynchronous Delegates
Topic Objective
To describe how to use
delegate objects to make ! Delegate object provides the ability to call a
asynchronous calls. synchronous method in an asynchronous manner
Lead-in # Compiler generates synchronous invoke method and
You can make an
asynchronous method call
asynchronous methods: BeginInvoke and EndInvoke
on an object even if the ! Asynchronous calls follow the design pattern
object’s class does not
provide explicit support for # Start operation with BeginInvoke
asynchronous operations by
using the asynchronous # Use callback, polling, call to EndInvoke, or wait to
methods of a delegate determine completion
object.
# Call EndInvoke to get results

*ILLEGAL FOR NON-TRAINER USE**

You can make an asynchronous method call on an object even if the object’s
class does not provide explicit support for asynchronous operations by using the
asynchronous methods of a delegate object.

Calling a synchronous method asynchronously

For each delegate class the Visual C# compiler generates BeginInvoke and
EndInvoke methods that provide the ability to call a synchronous target
method in an asynchronous manner.
If the BeginInvoke method is called, the runtime queues the request and returns
immediately to the caller. The target method will be called on a thread from the
thread pool. The original thread that submitted the request is free to continue
executing in parallel to the target method, which is running on a thread pool
thread.
If a callback has been specified on BeginInvoke, it is called when the target
method returns. In the callback, the EndInvoke method is used to obtain the
return value and the in/out parameters. If the callback is not specified on
BeginInvoke, you can use the other asynchronous design pattern techniques,
for example polling, on the original thread that submitted a request.
86 Module 14 (Optional): Threading and Asynchronous Programming

Using an asynchronous delegate

In the following example, which factorizes a number, you can see how to use a
delegate to make an asynchronous call.
The code for this demonstration is located in <install folder>\Democode\
Mod14\Demo14.7.
In this example, an asynchronous call is invoked on the Factorize method in
the PrimeFactorizer class, which is declared as follows:
public class PrimeFactorizer
{
public bool Factorize(
int factorizableNum,
ref int primefactor1,
ref int primefactor2)
{
// code to factorize the number
}
}

First a delegate for the Factorize is defined:

public delegate bool FactorizeDelegate(
int factorizableNum,
ref int primefactor1,
ref int primefactor2);

When the compiler emits the FactorizeDelegate delegate class after parsing its
definition, it generates the BeginInvoke and EndInvoke methods, in addition
to the Invoke method. The BeginInvoke and EndInvoke methods follow the
asynchronous design pattern’s method signatures, as follows:
public class FactorizeDelegate: delegate
{
public bool Invoke(
int factorizableNum,
ref int primefactor1,
ref int primefactor2);

// The following code was supplied by the compiler.

public IAsyncResult BeginInvoke(
int factorizableNum,
ref int primefactor1,
ref int primefactor2,
AsyncCallback cb,
Object AsyncState
);

// The following code was supplied by the compiler.

public bool EndInvoke(
ref int primefactor1,
ref int primefactor2,
IAsyncResult ar);
}
Module 14 (Optional): Threading and Asynchronous Programming 87

Next, the method to be called when the operation completes is defined:

public class ProcessFactorizedNumber
{
private int _ulNumber;

public ProcessFactorizedNumber(int number)

{
_ulNumber = number;
}

// the qualifier is one-way, see Note

[OneWayAttribute()]
public void FactorizedResults(IAsyncResult ar)
{
int factor1=0, factor2=0;

// Extract the delegate from the AsyncResult.

FactorizeDelegate fd =
(FactorizeDelegate)((AsyncResult)ar).AsyncDelegate;

// Obtain the result.

fd.EndInvoke(ref factor1, ref factor2, ar);

// Output results.
Console.WriteLine(
"On CallBack: Factors of {0} : {1} {2}",
_ulNumber, factor1, factor2);
}
}

Note The OneWayAttribute marks a method as one way, without a return

value and out or ref parameters. When one-way methods are called, no reply
message, status, or other information is expected.
88 Module 14 (Optional): Threading and Asynchronous Programming

The asynchronous operation is started by calling BeginInvoke as follows:

public void FactorizeNumber1()
{
//create the necessary arguments
// delegate to method to be called asynchronously
PrimeFactorizer pf = new PrimeFactorizer();
FactorizeDelegate fd = new
FactorizeDelegate(pf.Factorize);

// arguments for the Factorize method

int factorizableNum = 1000589023, temp=0;

// create the callback delegate

// to be called when the call completes

// first create an instance of the class which

// contains the callback method
ProcessFactorizedNumber fc = new
ProcessFactorizedNumber(factorizableNum);
// then create an AsyncCallback delegate to the method
AsyncCallback cb = new
AsyncCallback(fc.FactorizedResults);

// Asynchronously invoke the Factorize method.

IAsyncResult ar = fd.BeginInvoke(
factorizableNum,
ref temp,
ref temp,
cb,
null);

//
// Do some other useful work.
//. . .
}
Module 14 (Optional): Threading and Asynchronous Programming 89

An alternative approach to using a callback function is to wait for completion,

as shown in the following code:
public void FactorizeNumber2()
{
PrimeFactorizer pf = new PrimeFactorizer();
FactorizeDelegate fd = new
FactorizeDelegate(pf.Factorize);

int factorizableNum = 1000589023, temp=0;

// Asynchronously invoke the Factorize method on pf.

IAsyncResult ar = fd.BeginInvoke(
factorizableNum,
ref temp,
ref temp,
null,
null);

ar.AsyncWaitHandle.WaitOne(10000, false);

if (ar.IsCompleted)
{
int factor1=0, factor2=0;

// Obtain the result.

fd.EndInvoke(ref factor1, ref factor2, ar);

// Output results.

Console.WriteLine(
"After Using Wait Handle: Factors of {0}: {1} {2}",
factorizableNum, factor1, factor2);
}
}
90 Module 14 (Optional): Threading and Asynchronous Programming

Multimedia: Asynchronous Programming

Topic Objective
To illustrate asynchronous
programming using
Delegate objects.
Lead-in
This animation illustrates the
.NET Framework common
language runtime’s support
for asynchronous
programming using
Delegate objects.

*ILLEGAL FOR NON-TRAINER USE**

To launch the animation, This animation illustrates the .NET Framework common language runtime
click the button in the lower- support for asynchronous programming using Delegate objects.
left corner of the slide.
Module 14 (Optional): Threading and Asynchronous Programming 91

Demonstration: Using a Delegate

Topic Objective
To demonstrate how to use
a delegate object to make
asynchronous calls.
Lead-in
In this demonstration, you
will see how to use a
delegate object to make
asynchronous calls.

*ILLEGAL FOR NON-TRAINER USE**

This demonstration shows how to use a delegate object to make asynchronous
calls. The asynchronous call is made by using a callback method and by waiting
for the completion event.
The code for this demonstration is located in <install folder>\Democode\
Mod14\Demo14.7.
The output is similar to the following:
On CallBack: Factors of 1000589023 : 7 142941289
After Using Wait Handle : Factors of 1000589023 : 7 142941289
92 Module 14 (Optional): Threading and Asynchronous Programming

Lab 14: Working With Multithreaded Applications

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will create
thread-safe code that has
both System.Thread.Timer
and background thread
objects. In addition you will
make asynchronous calls
using delegates.

*ILLEGAL FOR NON-TRAINER USE**

Explain the lab objectives.
Objectives
After completing this lab, you will be able to:
! Create thread-safe methods using the C# lock keyword.
! Create, start, and dispose of a System.Thread.Timer object to periodically
perform an action.
! Create, start, and interrupt a background thread.
! Make an asynchronous method call by using delegates and a callback
method according to the .NET Framework asynchronous design pattern.

Lab Setup
Starter and solution files are associated with this lab. The starter files are in the
folder <install folder>\Labs\Lab14\Starter. The solution files for this lab are in
the folder <install folder>\Labs\Lab14\Solution.
Module 14 (Optional): Threading and Asynchronous Programming 93

Scenario
In this scenario, you use a Windows Forms client to invoke methods on a
logger server that writes messages to a log file. When starting the logger server
the client specifies the filename to use as a log file. After the logger server
starts, it opens the log file and begins two concurrent operations. In the first
operation, the server periodically writes the date and time to the log file; the
server does this by using a System.Thread.Timer object that uses a thread
from the thread pool.
In the second operation, the server periodically updates the client’s progress bar
to indicate to the user that the logger service is running. The server does this by
creating and starting a background thread. When the user stops the logger
server, the server terminates both concurrent operations and closes the log file.
While the logger server is running, the client can invoke a synchronous or an
asynchronous write of a text string to the log file. The asynchronous write is
done according to the .NET Framework asynchronous design pattern. The client
starts the asynchronous write by calling the BeginInvoke method of a delegate
to the logger server’s write method. The client, as a parameter to this call,
supplies an AsyncCallback delegate object that refers to the client’s method
that is called when the write operation completes.
Because multiple client calls to the server can execute concurrently, the server’s
methods must be implemented in a thread-safe manner.

Estimated time to complete this lab: 50 minutes

94 Module 14 (Optional): Threading and Asynchronous Programming

Exercise 1
Creating Thread-safe Methods
In this exercise, you will add thread-safe code to the MyLogger static methods
to start the logger, stop the logger, and write to the log file.

! Implement the StartLogger method

1. In Visual Studio .NET, open the Multithreading project which is located in
<install folder>\Labs\Lab14\Starter.
2. Open the file Form1.cs and locate the following comment for the
StartLogger method of the MyLogger class:
// TODO - Exercise 1.1: Add code to start logger

Note You can use the Visual Studio .NET Task List window to quickly
locate this code. To display this window, on the View menu, click Show
Tasks, and click All.

3. Use a lock statement to ensure that only one thread at a time executes the
method’s code.
Because StartLogger is a static method, you lock on the System.Type
object of the MyLogger class. You can obtain this object by using the
following expression:
typeof(MyLogger)

Place the remainder of the StartLogger method’s code within the lock
statement block.
4. Create a conditional expression that evaluates whether the logger is running.
If the logger is running, throw an InvalidOperationException exception. If
the logger is not running (loggerRunning is false):
a. Initialize numberOfWrites to zero.
b. Create a FileStream object for the file that is specified in the filename
parameter of the StartLogger method. The new FileStream object also
takes the filename, FileMode.OpenOrCreate and FileAccess.Write
parameters.
c. Create a StreamWriter object and pass in the new FileStream object.
This new object should be assigned to the existing static member
variable w.
d. Set the file pointer to the end of the new stream by calling the
StreamWriter object’s seek method as follows:
w.BaseStream.Seek(0, SeekOrigin.End);

e. Write to the stream by using the following format and supplying the
current time and date as the parameters:
"\nStartLogger – Time: {0} {1} \n\n"
Module 14 (Optional): Threading and Asynchronous Programming 95

f. Flush the stream.

g. Set the existing static member variable form to the value of the
parameter aForm in the StartLogger method.
h. Set the existing static member variable mi to a new delegate object of
type MethodInvoker that refers to the form object’s UpdateProgress
method.
i. Set loggerRunning to true.

! Implement the StopLogger method

1. In Form1.cs, locate the following comment for the StopLogger method of
the MyLogger class:
// TODO - Exercise 1.2: Add code to stop logger
2. Use a lock statement to ensure that only one thread at a time executes the
static method’s code.
Place the remainder of the StopLogger method’s code within the lock
statement block.
3. Create a conditional expression that evaluates whether the logger is running.
If the logger is not running, throw an InvalidOperationException
exception. If the logger is running (loggerRunning is true):
a. Write to the stream by using the following format and supplying the
current time and date as the parameters:
"\nStopLogger – Time: {0} {1} \n\n"

b. Close the stream.

c. Set loggerRunning to false.
96 Module 14 (Optional): Threading and Asynchronous Programming

! Implement the WriteLog method

1. In Form1.cs, locate the following comment for the WriteLog method of the
MyLogger class:
// TODO - Exercise 1.3: Add code to write to logger
2. Use a lock statement to ensure that only one thread at a time executes the
static method’s code.
Place the remainder of the WriteLog method’s code within the lock
statement block.
3. Create a variable of type int that is named writeCount and initialize it to
the value of numberOfWrites.
4. Create a conditional expression that evaluates whether the logger is running.
If the logger is not running, throw an InvalidOperationException
exception. If the logger is running (loggerRunning is true):
a. Make the thread sleep for 2 seconds.
b. Increment the value of writeCount by 1.
c. Write to the stream by using the following format and supplying
writeCount and logText as the parameters:
"\nCount: {0} Text: {1} - Time:"

d. Write to the stream by using the following format and supplying the
current time and date as the parameters:
"{0} {1} \n\n"

e. Flush the stream.

f. Set numberOfWrites to the value of writeCount.
5. Return writeCount.
Module 14 (Optional): Threading and Asynchronous Programming 97

! Test the application

1. Build and run the application by using Visual Studio .NET. Ignore warning
messages about fields that are never used.
2. In the Text To Log field, type Hello World.
3. To check the error reporting, click Synchronous Write, and note the
following message in the status bar at the bottom of the form:
“Invalid Operation - Write failed because logger was stopped”
4. Click Start Logger, and note the Logger State Indicator progress bar and
the following message in the status bar:
“Logger started”
5. Click Synchronous Write, and note that after a pause of 2 seconds the
following message is displayed in the status bar:
“Log written, count = 1”
6. Click Synchronous Write, and note that after a pause of 2 seconds the
following message is displayed in the status bar:
“Log written, count = 2”
7. Click Stop Logger, and note that the message in the status bar now says:
“Logger stopped”
8. Use Visual Studio .NET to view the log file Log.txt, that was created in the
same folder as the multithreading application’s executable program:
<install folder>\Labs\Lab14\Starter\Multithreading\bin\Debug
You should see output that is similar to the following:
StartLogger - Time: 11:09:48 AM Wednesday, September 19,
2001

Count:1 Text: Hello World - Time:11:10:40 AM Wednesday,

September 19, 2001

Count:2 Text: Hello World - Time:11:11:30 AM Wednesday,

September 19, 2001

StopLogger - Time:11:11:56 AM Wednesday, September 19, 2001

9. Stop the application and delete Log.txt.

98 Module 14 (Optional): Threading and Asynchronous Programming

Exercise 2
Periodically Writing to a Log File
In this exercise, you will add code to the MyLogger class to use a
System.Thread.Timer object. This object is used to periodically write a
message to the log file indicating that the logger is alive when the logger is
running.

! Create the Timer object

1. In Form1.cs, locate the following comment for the StartLogger method of
the MyLogger class:
// TODO - Exercise 2.1: Add code to periodically call !
a method using a System.Threading.Timer object

2. Locate the line of code that sets loggerRunning to true, and after this line
assign to the static member variable timer a new object of type
System.Threading.Timer.
The new object should call the MyLogger class’s LogStatus method every
5 seconds. LogStatus is a static method whose delegate type is
TimerCallback.

! Dispose of the Timer object

1. In Form1.cs, locate the following comment for the StopLogger method of
the MyLogger class:
// TODO - Exercise 2.2: Add code to dispose of the!
System.Threading.Timer object

2. Locate the line of code that writes the string "\nStopLogger - Time:"
to the log file and before this line add code that invokes the Dispose
method on the timer object.

! Add the Timer object that writes logger alive messages periodically to
the log file
1. In Form1.cs, locate the following comment for the LogStatus method of the
MyLogger class:
// TODO - Exercise 2.3: Add Timer callback method code to!
write the date and time to the log

2. Write to the stream the following string:

"\nLogger Alive: "

3. Once again, write to the stream by using the following format and supplying
the current time and date as the parameters:
"{0} {1} \n\n"
Module 14 (Optional): Threading and Asynchronous Programming 99

! Test the application

1. Build and run the application by using Visual Studio .NET. Ignore warning
messages about fields that are never used. Ensure that you have deleted the
file Log.txt that was created in the preceding exercise.
2. In the Text To Log field, type Hello World.
3. Click Start Logger, and note the following message in the status bar:
“Logger started”
4. Click Synchronous Write, and note that after a pause of 2 seconds the
following message is displayed in the status bar:
“Log written, count = 1”
5. Click Synchronous Write, and note that after a pause of 2 seconds the
message in the status bar changes to:
“Log written, count = 2”
6. Click the Stop Logger button and note that the message in the status bar
now says;
“Logger stopped”
7. Use Visual Studio .NET to view the file Log.txt that was created in the same
folder as the multithreading application’s executable program:
<install folder>\Labs\Lab14\Starter\Multithreading\bin\Debug
You should see output that is similar to the following:

StartLogger - Time: 11:47:21 AM Wednesday, September 19,

2001

Logger Alive: 11:47:21 AM Wednesday, September 19, 2001

Count:1 Text: Hello World - Time:11:47:24 AM Wednesday,

September 19, 2001

Logger Alive: 11:47:26 AM Wednesday, September 19, 2001

Count:2 Text: Hello World - Time:11:47:27 AM Wednesday,

September 19, 2001

StopLogger - Time:11:47:28 AM Wednesday, September 19, 2001

8. Stop the application and delete Log.txt.

100 Module 14 (Optional): Threading and Asynchronous Programming

Exercise 3
Providing the User with Status
In this exercise, you will add code to the MyLogger class to use a background
thread that periodically advances the Progress Bar in the user interface
whenever the logger is running.

! Create the background thread

1. In Form1.cs, locate the following comment for the StartLogger method of
the MyLogger class:
// TODO - Exercise 3.1: Add code to start a background!
thread

2. Locate the line of code that assigns to the static member variable timer a
new object of type System.Threading.Timer and after this line, add code
to do the following steps.
3. Create a new object of type Thread
The Thread object is initialized with a delegate object of type ThreadStart
that refers to the ThreadProc method of the MyLogger class. This new
object should be assigned to the existing static member variable
timerThread.
4. Make timerThread a background thread by using its IsBackground
property.
5. Start the timerThread background thread.

! Interrupt the background thread

1. In Form1.cs, locate the following comment for the StopLogger method of
the MyLogger class:
// TODO - Exercise 3.2: Add code to stop a background!
thread

2. Locate the line of code that invokes the Dispose method on the timer object
and before this line, set up a conditional expression that checks whether the
background thread is not null. If the background thread named
timerThread is not null:
a. Call the timerThread Interrupt method.
b. Assign timerThread, form, and mi to null.
Module 14 (Optional): Threading and Asynchronous Programming 101

! Advance the form’s progress bar periodically

1. In Form1.cs, locate the following comment for the ThreadProc method of
the MyLogger class:
// TODO - Exercise 3.3: Add code to update the client's!
progress indicator

2. In a try/catch block’s try section, insert a while(true) statement whose

block contains the following steps:
a. Call the form object’s BeginInvoke method.
Pass as the BeginInvoke method’s parameter the delegate object of type
MethodInvoker that refers to the form object’s UpdateProgress
method. This object was created in the StartLogger method and is
named mi.
b. Make the thread sleep for ½ second.
3. In the try/catch block’s catch section add code to do the following:
a. Catch exceptions of the type ThreadInterruptedException.
b. Within the catch block, do nothing.
This will resolve the exception and the thread will terminate gracefully.

! Test the application

1. Build and run the application by using Visual Studio .NET. Ensure that you
have deleted the file Log.txt that was created in the preceding exercise.
2. In the Text To Log field, type Hello World.
3. Click Start Logger.
Note that the Logger State Indicator progress bar is advancing and note
the following message in the status bar.
“Logger started”
4. Click Synchronous Write, and note that the progress bar stops advancing.
After a pause of 2 seconds, the progress bar jumps ahead and the following
message is displayed in the status bar.
“Log written, count = 1”
5. Click Synchronous Write, and note that the progress bar stops advancing.
After a pause of 2 seconds, the progress bar jumps ahead and the following
message is displayed in the status bar.
“Log written, count = 2”
6. Click Stop Logger.
Note that the Logger State Indicator progress bar has stopped advancing
and note that the message in the status bar now says:
“Logger stopped”
102 Module 14 (Optional): Threading and Asynchronous Programming

7. Use Visual Studio .NET to view the file Log.txt that was created in the same
folder as the multithreading application’s executable program:
<install folder>\Labs\Lab14\Starter\Multithreading\bin\Debug
You should see output that is similar to the following:
StartLogger - Time: 11:56:44 AM Wednesday, September 19,
2001

Logger Alive: 11:56:44 AM Wednesday, September 19, 2001

Count:1 Text: Hello World - Time:11:56:47 AM Wednesday,

September 19, 2001

Logger Alive: 11:56:49 AM Wednesday, September 19, 2001

Count:2 Text: Hello World - Time:11:56:50 AM Wednesday,

September 19, 2001

StopLogger - Time:11:56:53 AM Wednesday, September 19, 2001

8. Stop the application and delete the Log.txt.

Module 14 (Optional): Threading and Asynchronous Programming 103

Exercise 4
Making an Asynchronous Method Call
In this exercise, you will add code that uses a delegate object to begin an
asynchronous invocation of the WriteLog method of the MyLogger class. The
code will specify a method to be called when the WriteLog method completes.
You will add code to this method to obtain the results of the WriteLog method
and post the results to the form’s status bar.

! Create the event handler code that initiates the asynchronous write
1. In Form1.cs, locate the following comment for the button4_Click method
of the Form1 class:
// TODO - Exercise 4.1: Add code to begin asynchronous!
log write

2. Set the statusBar1.Text property to an empty string.

3. Create a delegate named wld of type WriteLogDelegate that refers to the
WriteLog static method of the MyLogger class.
4. Create a delegate object named cb of type AsyncCallback that refers to the
current Form1 object’s AsynchronousWriteResults method.
5. Initialize a variable named ar of type IAsyncResult to the value that is
returned by invoking the wld object’s BeginInvoke method.
BeginInvoke should include the following three parameters:
a. The textBox2 Text property
b. The cb delegate object
c. null
104 Module 14 (Optional): Threading and Asynchronous Programming

! Create the code that is called when the asynchronous method call
completes
1. In Form1.cs, locate the following comment for the
AsynchronousWriteResults method of the Form1 class:
// TODO - Exercise 4.2: Add code to this callback method to handle !
the results of asynchronous log write
2. Create a delegate object name wld of type WriteLogDelegate and set wld
to refer to the method that was previously specified in the button4_Click
method’s BeginInvoke method call by doing the following:
a. Explicitly cast the parameter that is named ar of type IAsyncResult to
type AsyncResult and get its AsyncDelegate property.
b. Explicitly cast the result of the preceding step to type
WriteLogDelegate and assign this value to wld.
3. Create a try/catch block and in the try section, add code to do the
following:
a. Initialize a variable named count of type int to the result of calling the
wld object’s EndInvoke method with the single parameter named ar.
b. Assign to the existing variable named resultString of type string the
following value:
"Log written asynchronously, " + count.ToString()

4. In the try/catch block’s catch section, add code to do the following:

a. Catch exceptions of the type InvalidOperationException.
b. Assign to the existing variable named resultString of type string the
following value:
"Invalid Operation - Asynchronous write failed because !
logger was stopped"

5. To update the form’s control on the thread that originally created the
control, call the BeginInvoke method of the current Form1 object.
BeginInvoke takes a single parameter that is a delegate of type
MethodInvoker that refers to the current Form1 object’s
UpdateAsynchronousWriteStatus method.

! Test the application

4. Click Asynchronous Write, and note that the progress bar continues to
advance.
After a pause of 2 seconds, the following message is displayed in the status
bar:
“Log written asynchronously, 1”
5. Click Asynchronous Write, and note that after a pause of 2 seconds the
message in the status bar changes to:
“Log written asynchronously, 2”
6. Click Asynchronous Write twice in quick succession, and after the
message “Log written asynchronously, 4” is displayed in the status bar.
Click Stop Logger.
Note that the Logger State Indicator progress bar stops advancing and note
that the following message is displayed in the status bar:
“Logger stopped”
7. Use Visual Studio .NET to view the file Log.txt that was created in the same
folder as the multithreading application’s executable program:
<install folder>\Labs\Lab14\Starter\Multithreading\bin\Debug
You should see output that is similar to the following:
StartLogger - Time: 12:04:27 PM Wednesday, September 19,
2001

Logger Alive: 12:04:27 PM Wednesday, September 19, 2001

Count:1 Text: Hello Asynchronous World - Time:12:04:30 PM

Wednesday, September 19, 2001

Logger Alive: 12:04:32 PM Wednesday, September 19, 2001

Count:2 Text: Hello Asynchronous World - Time:12:04:33 PM

Wednesday, September 19, 2001

Count:3 Text: Hello Asynchronous World - Time:12:04:36 PM

Wednesday, September 19, 2001

Logger Alive: 12:04:37 PM Wednesday, September 19, 2001

Count:4 Text: Hello Asynchronous World - Time:12:04:38 PM

Wednesday, September 19, 2001

StopLogger - Time:12:04:41 PM Wednesday, September 19, 2001

8. Stop the application and delete Log.txt.

106 Module 14 (Optional): Threading and Asynchronous Programming

If Time Permits
Demonstrating a Race Condition
In this exercise, you will remove the lock in the WriteLog method of the
MyLogger class. You will note the errors resulting from the existence of a race
condition that occurs when multiple asynchronous calls cause multiple threads
to concurrently access the static variables of the MyLogger class.

! Create the potential for a race condition by removing the WriteLog

method lock
1. In Form1.cs, locate the WriteLog method of the MyLogger class and
comment out the line(s) that contain the lock statement and the opening
brace of the lock statement block.
2. Just before the end of the method, comment out the closing brace of the lock
statement.

! Test the application

1. Build and run the application by using Visual Studio .NET. Ensure that you
have deleted the file Log.txt that was created in the preceding exercise.
2. In the Text To Log field, type Hello Asynchronous World.
3. Click Start Logger.
Note that the Logger State Indicator progress bar is advancing and note
the following message in the status bar:
“Logger started”
4. Click Asynchronous Write, and note that the progress bar continues to
advance.
After a pause of 2 seconds, the following message is displayed in the status
bar:
“Log written asynchronously, 1”
5. Click Asynchronous Write, and note that after a pause of 2 seconds the
message in the status bar changes to:
“Log written asynchronously, 2”
6. Click Asynchronous Write twice in quick succession, wait for about 10
seconds, and then click Stop Logger.
Note that the Logger State Indicator progress bar stops advancing and note
the following message is displayed in the status bar:
“Logger stopped”
Module 14 (Optional): Threading and Asynchronous Programming 107

Logger Alive: 12:40:24 PM Wednesday, September 19, 2001

Count:1 Text: Hello Asynchronous World - Time:12:40:28 PM

Wednesday, September 19, 2001

Logger Alive: 12:40:30 PM Wednesday, September 19, 2001

Count:2 Text: Hello Asynchronous World - Time:12:40:30 PM

Wednesday, September 19, 2001

Logger Alive: 12:40:35 PM Wednesday, September 19, 2001

Count:3 Text: Hello Asynchronous World - Time:12:40:35 PM

Wednesday, September 19, 2001

Count:3 Text: Hello Asynchronous World - Time:12:40:35 PM

Wednesday, September 19, 2001

Logger Alive: 12:40:39 PM Wednesday, September 19, 2001

Logger Alive: 12:40:44 PM Wednesday, September 19, 2001

StopLogger - Time:12:40:44 PM Wednesday, September 19, 2001

Note Because of the race condition during the last two asynchronous
writes, the write counter is the same for both of these writes.

8. Stop the application and delete Log.txt.

108 Module 14 (Optional): Threading and Asynchronous Programming

Review
Topic Objective
To reinforce module
objectives by reviewing
key points. ! Introduction to Threading
Lead-in ! Using Threads in .NET
The review questions cover
some of the key concepts ! Thread Safety
taught in the module.
! Special Thread Topics
! Asynchronous Programming in .NET

*ILLEGAL FOR NON-TRAINER USE**

1. State one advantage and one disadvantage of using multiple threads in an
application.
Advantages: Threading maintains the responsiveness of the user
interface while background processing is occurring, allows for subtasks
to be assigned different priorities, and allows a long-running task to be
done in the background.
Disadvantages: Overhead with thread creation and running may
decrease performance; sharing data between threads is complex and
prone to errors.

2. Write the code to execute a thread on the static method in a class named
MyClass that is declared: static void MyMethod().
Thread t1 = new
Thread(new ThreadStart(MyClass.MyMethod));
t1.Start();

3. Name the three .NET Framework categories of techniques for providing

thread safety when data must be shared between concurrently executing
threads.
Synchronized Context, Synchronized Code Regions, Manual
Synchronization.
Module 14 (Optional): Threading and Asynchronous Programming 109

4. If you want to get or set properties, or call methods on a control from a

background thread, what must you do?
You must marshal the call to the thread on which the control was
created by using one of the control’s thread safe methods: Invoke,
BeginInvoke, and EndInvoke.

5. In the second part of an asynchronous call operation, name the four ways
that the caller can know when the asynchronous operation has completed.
Callback method, poll, call end method, wait for event.
THIS PAGE INTENTIONALLY LEFT BLANK
Module 15 (Optional):
Interoperating Between
Managed and
Contents
Unmanaged Code
Overview 1
Integration Services 2
Platform Invoke 7
Lab 15.1: Calling Win32 APIs 16
Calling COM Objects from Managed Code 20
Lab 15.2: Calling COM Objects 39
Calling .NET Objects from COM Objects 43
Review 55
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, places or events is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code iii

Instructor Notes
Presentation: After completing this module, students will be able to:
90 Minutes
! State the need for interoperability between Microsoft® .NET assemblies and
Lab: COM components.
60 Minutes
! Use platform invoke to call a function in a dynamic-link library (DLL).
! Expose the methods and properties of a COM object to an assembly.
! Describe the three ways to generate runtime callable wrappers.
! Use Microsoft Visual Studio® .NET to call a COM object.
! Use the Type Library Importer to generate metadata from a type library.
! Expose the methods and properties of a .NET Framework class to a COM
client.
! Use the Type Library Exporter to generate a type library for an assembly.
! Use the ClassInterfaceAttribute to control and modify the type of interface
that is generated for a .NET Framework class.

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach
this module.

Required Materials
To teach this module, you need the Microsoft PowerPoint® file 2349B_15.ppt.

Preparation Tasks
To prepare for this module, you should:
! Read all of the materials for this module.
! Complete the lab.
iv Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

Demonstrations
The following demonstrations are used to show how to create a managed
assembly from an unmanaged DLL file, and how to create a COM component
from a managed assembly.
In this module, use a Visual Studio .NET Command Prompt window to obtain a
command prompt window with the appropriate environment values that are
required for .NET tools.

Demonstration: Using the Type Library Importer

Before running the demo, the COM object needs to be registered in the system
registry.

Important To use Microsoft Visual Studio .NET tools within a command

prompt window, the command prompt window must have the proper
environment settings. The Visual Studio .NET Command Prompt window
provides such an environment. To run a Visual Studio .NET Command Prompt
window, click Start, All Programs, Microsoft Visual Studio .NET, Visual
Studio .NET Tools, and Visual Studio .NET Command Prompt.

! To register the COM object

1. At the command prompt, change the current folder to <install folder>\
Democode\Mod15\Demo15.1.
2. Run regsvr32 TLBIMPDemo.dll to register the COM object.
3. A dialog box appears informing you that the registration succeeded. To
dismiss the dialog box, click OK.

In this demonstration, students will see how to use the Type Library Importer to
generate metadata for a DLL, and then use the metadata to create a managed
wrapper for the component.

! To create a managed wrapper for the TLBIMPDemo component and

generate metadata by using the Type Library Importer
1. Run the Type Library Importer on TLBIMPDemo.dll, by typing the
following command in a Visual Studio .NET Command Prompt window:
tlbimp TLBIMPDemo.dll /out:Calculator.dll

The resulting DLL is a .NET assembly and is named Calculator.dll.

2. Build the calculator application by typing the following command:
csc /reference:Calculator.dll CalcUI.cs
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code v

! To run the calculator application and view the metadata of

Calculator.dll
1. Run CalcUI.exe from the command prompt by typing the following
command:
CalcUI

2. Exit CalcUI.exe.
3. In a Visual Studio .NET Command Prompt window, run the Microsoft
intermediate language (MSIL) Disassembler on Calculator.dll by typing the
following command:
ildasm /adv Calculator.dll

4. To display the contents of the manifest, double-click MANIFEST.

5. Notice the assembly Calculator that appears near the end of the manifest. It
should look similar to the following example:
.assembly Calculator
{
.custom instance void!
[mscorlib]System.Runtime.InteropServices.GuidAttribute::
.ctor(string) = (…
.custom instance void!
[mscorlib]System.Runtime.InteropServices.!
ImportedFromTypeLibAttribute::.ctor(string) = …!
// ...TLBIMPDemo..
.hash algorithm 0x00008004
.ver 1:0:0:0
}

6. This entry in the manifest demonstrates the referencing of an unmanaged

COM component from managed code through the interoperability services
provided by the .NET Framework.
vi Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

Demonstration: Using the Type Library Exporter

In this demonstration, students will see how to use the Type Library Exporter to
generate a type library that describes the types defined in a common language
runtime assembly.

! To generate a type library from an assembly by using the Type Library

Exporter
1. In a Visual Studio .NET Command Prompt window, change the current
folder to <install folder>\Democode\Mod15\Demo15.2.
2. To create a type library for Calculator.dll, type the following command:
tlbexp Calculator.dll /out:Calculator.tlb

3. The Type Library Exporter creates the Calculator.tlb file.

! To view the contents of the type library

1. Start a Visual Studio .NET Command Prompt.
2. Type oleview and press Enter.
3. In the OLE/COM Object Viewer window, on the File menu, click View
TypeLib.
4. In the Open dialog box, move to <install_folder>\Democode\
Mod15\Demo15.2, select Calculator.tlb, and then click Open. The
ITypeLib Viewer window appears with the information that is found in the
type library.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code vii

Module Strategy
Use the following strategy to present this module:
! Integration Services
This module provides an introduction to COM interoperability and platform
invoke. Ensure that students understand the difference between calling an
API function that is implemented in a DLL and calling a COM component.
! Platform Invoke
Concentrate on the information in the slides titled “How Platform Invoke
Works” and “Calling Unmanaged Functions”.
! Calling COM Objects from Managed Code
Concentrate on the procedure for generating runtime callable wrappers, the
use of the type library importer, and the process for signature translation and
error handling.
! Calling .NET Objects from COM Objects
Ensure that students understand the export process when the Type Library
Exporter is used to generate a type library.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 1

Overview
Topic Objective
To provide an overview of
the module topics and
objectives.
! Integration Services
Lead-in ! Platform Invoke
In this module, you will learn
about interoperating ! Calling COM Objects from Managed Code
between managed and
unmanaged code. ! Calling .NET Objects from COM Objects

*ILLEGAL FOR NON-TRAINER USE**

After completing this module, you will be able to:
! State the need for interoperability between Microsoft® .NET assemblies and
COM components.
! Use platform invoke to call a function in a dynamic-link library (DLL).
! Expose the methods and properties of a COM object to an assembly.
! Describe the three ways to generate runtime callable wrappers.
! Use Microsoft Visual Studio® .NET to call a COM object.
! Use the Type Library Importer to generate metadata from a type library.
! Expose the methods and properties of a .NET Framework class to a COM
client.
! Use the Type Library Exporter to generate a type library for an assembly.
! Use the ClassInterfaceAttribute to control and modify the type of interface
that is generated for a .NET Framework class.
2 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

" Integration Services

Topic Objective
To introduce the services
provided by the .NET
Framework that allow ! Introduction to Platform Invoke
managed code to
! Introduction to COM Interoperability
interoperate with
unmanaged code. ! Interop Marshaling Overview
Lead-in
The .NET Framework
provides two services that
enable managed code to
interoperate with
unmanaged code. This
section provides an
overview of these two
services.

*ILLEGAL FOR NON-TRAINER USE**

When you adopt the .NET Framework to develop your applications, you may
still have a lot of unmanaged code libraries implemented as DLLs and COM
components. Code executing under the control of the runtime is called managed
code. Conversely, code that runs outside the runtime is called unmanaged code.
COM components, Microsoft ActiveX® interfaces, and Microsoft Win32® API
functions are examples of unmanaged code.
You do not have to convert all of your existing unmanaged code to managed
code before you can use it with .NET Framework applications. The Microsoft
.NET Framework promotes interaction with COM components, COM+
services, external type libraries, and many operating system services. Data
types, method signatures, and error-handling mechanisms vary between
managed and unmanaged object models. The .NET Framework offers two
services—platform invoke and COM interoperability services—that allow
managed code to interoperate with existing unmanaged code.

Note The ActiveX Control Importer (Aximp.exe) can be used to convert type
definitions in a COM type library for an ActiveX control into a Microsoft
Windows® Forms control. For additional information, see “Tools and
Debuggers; Windows Forms ActiveX Control Importer (Aximp.exe)” in the
.NET Framework SDK documentation.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 3

Introduction to Platform Invoke

Topic Objective
To provide an overview of
platform invoke.
! Allows Managed Code to Call Unmanaged Functions
Lead-in That Are Implemented in a DLL
Platform invoke allows
managed code to ! Provides the Mechanism for
interoperate with
unmanaged APIs. # Finding and invoking unmanaged functions
# Marshaling managed arguments to and from
unmanaged code

*ILLEGAL FOR NON-TRAINER USE**

Platform invoke allows managed code to call unmanaged functions that are
implemented in a DLL. Platform invoke provides the mechanism for finding
and invoking unmanaged functions, as well as marshaling managed arguments
to and from unmanaged code.
When managed code calls an unmanaged function that is implemented in a
DLL, platform invoke locates the DLL that implements the function, loads the
DLL into memory, and locates the function address in memory. It then pushes
the function’s arguments onto the stack, marshals any data that has to be
marshaled, enables pre-emptive garbage collection, and transfers control to the
address of the unmanaged code.
4 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

Introduction to COM Interoperability

Topic Objective
To provide an overview of
COM interoperability
! COM and .NET Differences Include:
services provided by the
.NET Framework. # Lifetime management - reference counting versus
garbage collection
Lead-in
COM interoperability # Service discovery - QueryInterface versus Reflection
services allow managed
# Object memory – fixed versus movable
code to interoperate with
COM components. ! Runtime Callable Wrapper (RCW)
# Used by managed clients to call a method on a COM object
! COM Callable Wrapper (CCW)
# Used by COM clients to call a method on a managed object

*ILLEGAL FOR NON-TRAINER USE**

COM differs from the .NET Framework object model in several important
ways:
! Clients of COM objects must manage the lifetime of those objects; the
common language runtime manages the lifetime of objects in its
environment.
! Clients of COM objects discover whether a service is available by
requesting an interface that provides that service and getting back an
interface pointer, or not. Clients of .NET objects can obtain a description of
an object's functionality using Reflection.
! Managed objects reside in memory managed by the .NET Framework
execution environment. The execution environment can move objects
around in memory for performance reasons and update all references to the
objects it moves. Unmanaged clients, having obtained a pointer to an object,
rely on the object to remain at the same location. These clients have no
mechanism for dealing with an object whose location is not fixed.

To overcome these differences, the runtime provides wrapper classes to make

both managed and unmanaged clients think they are calling objects within their
respective environment. Whenever your managed client calls a method on a
COM object, the runtime creates a runtime callable wrapper (RCW). RCWs
abstract the differences between managed and unmanaged reference
mechanisms, among other things. The runtime also creates a COM callable
wrapper (CCW) to reverse the process, enabling a COM client to call a method
on a .NET object.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 5

Interop Marshaling Overview

Topic Objective
To provide an overview of ! Interop marshaling governs how data is passed
interop marshalling. between managed and unmanaged memory during calls
Lead-in # Is a run time activity performed by the common language
Interop marshaling governs runtime marshaling service
how data is passed in
method arguments and ! Blittable data types are common to managed and
return values between unmanaged memory and require no conversion – data
managed and unmanaged types (C# keyword) :
memory during calls.
# System.Byte (byte) System.SByte (sbyte)
# System.Int16 (short) System.UInt16 (ushort)
# System.Int32 (int) System.UInt32 (uint)
# System.Int64 (long) System.IntPtr System.UIntPtr

*ILLEGAL FOR NON-TRAINER USE**

Interop marshaling governs how data is passed in method arguments and return
values between managed and unmanaged memory during calls. Interop
marshaling is a run-time activity performed by the common language runtime's
marshaling service.
Most data types have a common representation in both managed and
unmanaged memory and do not require special handling by the interop
marshaler. These types are called blittable types because they do not require
conversion when passed between managed and unmanaged code.
The following types from the System namespace are blittable types:
! System.Byte
! System.SByte
! System.Int16
! System.UInt16
! System.Int32
! System.UInt32
! System.Int64
! System.IntPtr
! System.UintPtr
6 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

Interop Marshaling Overview (continued)

Topic Objective
To complete the overiew of
interop marshalling.
! Non-blittable types have different or ambiguous
Lead-in representations in managed and unmanaged languages
Let’s discuss how non- and may require conversion
blittable types differ from
blittable types with regard to # For example, managed strings are non-blittable types
Interop marshaling and how
custom attributes may be ! The standard RCW or CCW usually provides adequate
used to in place of the marshaling for calls that cross the boundary between
standard marshaling COM and the .NET Framework
operations.
# Custom attributes can optionally adjust the way the
runtime represents managed and unmanaged code

*ILLEGAL FOR NON-TRAINER USE**

Non-blittable types have different or ambiguous representations in managed and
unmanaged languages. These types may require conversion when they are
marshaled between managed and unmanaged code. For example, managed
strings are non-blittable types because they can have several different
unmanaged representations, some of which can require conversion.
The following table lists non-blittable types from the System namespace.
Delegates, which are data structures that refer to a static method or to a class
instance, are also non-blittable.
Non-blittable type Description

System.Array Converts to a C-style or a SAFEARRAY.

System.Boolean Converts to a 1, 2, or 4-byte value with true as 1 or -1.
System.Char Converts to a Unicode or ANSI character.
System.Class Converts to a class interface.
System.Object Converts to a variant or an interface.
System.Mdarray Converts to a C-style array or a SAFEARRAY.
System.String Converts to a null-terminated string or to a BSTR.
System.Valuetype Converts to a structure with a fixed memory layout.
System.Szarray Converts to a C-style array or a SAFEARRAY.

In most cases, the standard RCW or CCW that is generated by the runtime
provides adequate marshaling for calls that cross the boundary between COM
and the .NET Framework. Using custom attributes, you can optionally adjust
the way the runtime represents managed and unmanaged code.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 7

" Platform Invoke

Topic Objective
To introduce platform
invoke.
! How Platform Invoke Works
Lead-in
In this section you will learn ! Calling a Win32 API From Managed Code
how platform invoke can be
used to call unmanaged ! Calling Unmanaged Functions
code.
! Pinning
! Marshaling
! Performance Considerations and Limitations of
Platform Invoke

*ILLEGAL FOR NON-TRAINER USE**

Platform invoke allows managed code to call unmanaged functions that are
implemented in a DLL. Platform invoke is primarily used to call C functions
that are part of the Win32 API. To use these functions, you must import the
DLL that hosts the functions. The .NET Framework provides default
marshaling to marshal data between managed and unmanaged code. You can,
however, override the marshaling provided by the .NET Framework whenever
you require custom marshaling to be performed.
8 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

How Platform Invoke Works

Topic Objective
To describe how platform
invoke executes methods
that are implemented in a
DLL.
Lead-in
This is how platform invoke
loads and executes a
method that is implemented
in a DLL.

*ILLEGAL FOR NON-TRAINER USE**

When platform invoke calls an unmanaged function, it performs the following
sequence of actions:
1. Platform invoke locates the DLL containing the function.
2. It loads the DLL into memory.
3. It locates the address of the function in memory and pushes its arguments
onto the stack, marshaling data as required.
4. Platform invoke then transfers control to the unmanaged function.

You provide the DLL and function information to platform invoke by

annotating your code. This information is used by platform invoke to locate the
DLL and load it into the memory of the process, after which the address of the
function is located and control is transferred.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 9

Calling a Win32 API From Managed Code

Topic Objective
To describe how to call a
Win32 API from managed
code. ! Declare the Method with the static and extern
C# Keywords
Lead-in
To use an unmanaged ! Import the DLL That Implements the Unmanaged
function that is implemented Function That You Wish to Call
in a DLL, you must first
import the DLL into your
[DllImport(<DLL
[DllImport(<DLL name>,
name>, EntryPoint=<function
EntryPoint=<function name>,
name>,
code.
CharSet=<type
CharSet=<type of
of characterset>]
characterset>]

! Optionally, Specify Custom Marshaling Information to

Override the .NET Framework Default Marshaling

*ILLEGAL FOR NON-TRAINER USE**

To call an unmanaged function, the first step is to annotate your code by
importing the DLL file in which the function is implemented. You use the
DllImport attribute to import the DLL. The DllImport attribute requires the
DLL_name argument, and also takes any of the following additional arguments.
Argument Description

EntryPoint Specifies the DLL entry point to be called.

CharSet Controls name mangling and the way that string arguments
should be marshaled to the function. The default is
CharSet.Ansi.
ExactSpelling Prevents an entry point from being modified to correspond to
the character set. If CharSet.Auto is enabled, the default is
False. Otherwise, the default is True.
CallingConvention Specifies the calling-convention values used in passing method
arguments. The default is Winapi.
PreserveSig Indicates that the managed method signature should not be
transformed into an unmanaged signature that returns an
HRESULT, and might have an additional [out, retval]
argument for the return value.
The default is True (the signature should not be transformed).
SetLastError Enables the caller to use the GetLastError Win32 API
function to determine whether an error occurred while
executing the method. In Microsoft Visual Basic®, the default is
True; in C# and C++, the default is False.

If the DLL has both an ANSI and a Unicode implementation of the same
function, then the CharSet parameter specifies which version of the function is
called.
10 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

Calling Unmanaged Functions

Topic Objective
To describe how to annotate
unmanaged method calls so
! To Call a Function That Is Implemented in an Unmanaged DLL
that they can be called from
.NET Framework # Add a using statement for System.Runtime.InteropServices
applications.
# Add a DllImport attribute to a method, specifying the name of the
Lead-in unmanaged DLL that exports the function to be called
Unmanaged methods that
# Declare with the static and extern C# keywords the method that is
are implemented as a DLL used to call unmanaged code without providing any implementation
and called from managed for the method
code must be annotated
before they can be executed
using
using System.Runtime.InteropServices;
System.Runtime.InteropServices;
by the runtime.
……
[DllImport("msvcrt.dll",
[DllImport("msvcrt.dll", CharSet=CharSet.Ansi)]
CharSet=CharSet.Ansi)]
public
public static
static extern
extern int
int puts(String
puts(String str);
str);

*ILLEGAL FOR NON-TRAINER USE**

When you call unmanaged functions from .NET Framework applications, you
Delivery Tip must add a DllImport attribute to a method that is to be used by platform
Refer to the .NET SDK for
more information about
invoke. The DllImport attribute is defined in
DllImport, calling System.Runtime.InteropServices. Platform invoke uses the information in the
conventions, marshaling, attribute to call the appropriate underlying DLL function, marshal parameters to
and character sets. the function, and return values from the function when the method is called.
The example on the slide shows the use of the DllImport attribute.
To annotate a method in managed code that is used to call a function in an
unmanaged DLL, you must specify the name of the DLL that exports the
unmanaged function. You must also specify with the static and extern C#
keywords the name of the exported function or its equivalent entry point
ordinal, if the exported function name is different than the name of the method
that you declared in the managed module. Optionally, you can specify a flag to
indicate the underlying calling convention and to automatically marshal string
data types correctly. The calling convention flag can be set to Cdecl, FastCall,
StdCall, ThisCall, or Winapi. If no calling convention is specified, Winapi is
the default. You can also optionally specify the character set to use as part of
the function call. The values that you can specify for the character set are ansi,
unicode, or auto.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 11

There are two general approaches when declaring methods that match
unmanaged functions:
! You can declare the method to call the unmanaged DLL without providing
any implementation for the method, as shown in the following example:
using System;
using System.Runtime.InteropServices;
…
[DllImport("msvcrt.dll", CharSet=CharSet.Ansi)]
public static extern int puts(String str);
…
static void Main()
{
String Str = "Hello World!";
puts(Str);
}

The compiler uses the method declaration to generate the metadata that the
runtime needs to locate and correctly marshal the call to the DLL. When
declaring the method in your managed code, you can substitute the
equivalent runtime types for the function’s types. In the previous example, a
string object is substituted for a character string.
! You can also declare a .NET Framework class that is a collection of
declarations for an API exported by an unmanaged DLL. The advantage of
creating such a class is that you do not have to declare and annotate the
methods for the unmanaged DLL that you want to call in all the applications
that you create. After it is created, you can include the class in your
application, and you can call the unmanaged functions that are declared in
the class as if they were .NET Framework methods.

Annotated methods behave like managed .NET Framework methods. When an

annotated method is called, platform invoke calls the unmanaged function,
marshaling any data that needs to be marshaled to and from the unmanaged
function.
12 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

Pinning
Topic Objective
To define pinning.
Lead-in ! Data Is Temporarily Locked in Its Current Memory
When data is marshaled Location to Keep It from Being Relocated by the
between managed and Common Language Runtime’s Garbage Collector
unmanaged code, it can
either be copied from one
! Pinning Is Performed When Data Has to Be Passed
memory location to another,
Between Managed and Unmanaged Code and
or it can be pinned. # Has a fixed layout and common data representation in
both managed and unmanaged memory
- or -
# Has a fixed layout but the data representation is different
in managed and unmanaged memory and the class is
marshaled by reference

*ILLEGAL FOR NON-TRAINER USE**

Pinning is a technique in which data is temporarily locked in its current
memory location to keep it from being relocated during garbage collection.
Whether data is copied or pinned during the marshaling process depends on the
type of the data and its InAttribute and OutAttribute.
When classes that have a fixed layout and common data representation in both
managed and unmanaged memory require marshaling, a pointer to the actual
object is passed to the called function. The called function is then free to change
the contents of the memory location being referenced by the pointer.
When classes have a fixed layout but the data representation is different in
managed and unmanaged memory and the class is marshaled by reference, the
called function receives a pointer to a copy of the data structure. If the
InAttribute is set, the copy is always initialized with the instance’s state. If the
OutAttribute is set, the state is always copied back in to the instance upon
return. If both the InAttribute and OutAttribute are set, the copy is always
initialized with the instance’s state, and the last state is always copied back into
the instance on return. If either attribute is omitted, the runtime may choose to
eliminate either copy as an optimization.
When classes that do not have a fixed layout—such as System.String and
System.Text.StringBuilder—have to be marshaled by value or by reference to
unmanaged code, the runtime typically copies the data of either type to a
secondary buffer and passes a reference to the buffer to the called function. The
reference is always allocated with CoTaskMemAlloc.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 13

Marshaling
Topic Objective
To describe how
marshalling is performed by
platform invoke. ! Platform Invoke Marshals Simple Data Types Between
Managed and Unmanaged Code
Lead-in
Platform invoke ! Custom Marshalling Can Be Specified by Using the
automatically marshals data MarshalAs Attribute
between unmanaged types
and managed types.
public
public static
static extern
extern int
int MessageBoxW(
MessageBoxW(
int h,
int h,
[MarshalAs(UnmanagedType.LPWStr)]
[MarshalAs(UnmanagedType.LPWStr)] string
string m,
m,
…);
…);

*ILLEGAL FOR NON-TRAINER USE**

For arguments that are simple data types—such as bytes or integers—platform
invoke marshals the managed argument to the corresponding unmanaged data
type. The following table shows how the data types used in the Win32 API
(wtypes.h) should be expressed in C#.
Data Type in wtypes.h C# Data Type

HANDLE int
BYTE byte
SHORT short
WORD ushort
INT int
UINT uint
LONG int
ULONG uint
BOOLEAN int
CHAR char
LPSTR (and most other string types) String for in, StringBuilder for inout
FLOAT float
DOUBLE double

If any parameter is passed by reference, the ref keyword in C# should be added

to the method declaration used to call unmanaged code.
14 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

For example, the GetUserNameEx Win32 API function has the following
declaration:
BOOLEAN GetUserNameEx(
EXTENDED_NAME_FORMAT NameFormat, // name format
LPTSTR lpNameBuffer, // name buffer
PULONG nSize // size of name buffer
);

To call this from managed code, you would use the following declaration:
[DllImport("secur32.dll", CharSet=CharSet.Auto)]
public static extern int GetUserNameEx (int nameFormat,
StringBuilder userName, ref uint userNameSize);

Notice that an integer is substituted for the enumeration parameter, a

StringBuilder object is substituted for the string parameter, and the ref
keyword is added to the last parameter, because it is passed by reference.
Your choice of data types may affect applications when the data types are
marshaled to and from managed code. For example, in Win32 APIs, a LONG
data type is 32 bits, whereas the C# long and Visual Basic .NET Long data
types are 64 bits.
When calling API functions, you can specify custom marshaling attributes by
adding a MarshalAsAttribute to the parameters of the function. You can also
use the MarshalAsAttribute with structures. When using the
MarshalAsAttribute with structures, you must also use the StructLayout
attribute to set the native layout of the structure.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 15

Performance Considerations and Limitations of Platform Invoke

Topic Objective
To list some performance
considerations and
limitations of using platform ! Platform Invoke Supports Only Integer Arguments to
invoke. Callback Functions
Lead-in ! Platform Invoke Does Not Support All Data Types
When calling unmanaged
code from managed code by ! Platform Invoke Supports Calling Only Global Functions
using platform invoke, you Exported from the DLL
must keep the following
limitations and performance ! Array Arguments That Are Passed by Reference and
considerations in mind. Copied Back Are Resized to 1

*ILLEGAL FOR NON-TRAINER USE**

Some of the limitations that you must keep in mind when calling unmanaged
functions by using platform invoke are:
! Platform invoke supports the callback mechanism. However, only integers
are currently permitted as the arguments to the callback function.
! Platform invoke does not support all data types.
! Platform invoke supports calling only global functions exported from the
DLL.
! When you call an unmanaged function, passing a reference to an array
argument, all the array elements are copied to an unmanaged buffer. When
the values are copied back, the size of that unmanaged buffer is no longer
known. Therefore, only one element is copied back. The array is resized
to 1.
16 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

Lab 15.1: Calling Win32 APIs

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will call a
Win32 API from managed
code.

*ILLEGAL FOR NON-TRAINER USE**

Objectives
After completing this lab, you will be able to call a Win32 API from managed
code.

Estimated time to complete this lab: 30 minutes

Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 17

Exercise 1
Calling a Win32 API from Managed Code
In this exercise, you will call Win32 APIs from managed code. This includes
adding DllImport attributes to methods in your class, and then invoking those
methods. The first unmanaged function you call retrieves the user name, and the
second unmanaged function you call displays the user name in a message box.

! Open the Visual Studio .NET project for this exercise and examine the
application UI
1. In Microsoft Windows® Explorer, move to <install folder>\Labs\
Lab15\Lab15.1\Starter.
2. Double-click CallingUnmanagedCode.csproj to open the project for this
exercise in Visual Studio .NET.
3. In the Solution Explorer pane, double-click ManagedCode.cs. The UI
design for the Windows Forms application appears. Examine the UI for a
moment to become familiar with it.
4. Press F7 to edit the code that implements the Windows Form application.

! Add the DllImport attribute for the method used to retrieve the user
name
• GetUserNameEx is the Win32 API to be called. The signature for this
function is as follows:
BOOLEAN GetUserNameEx(
EXTENDED_NAME_FORMAT NameFormat, // name format
LPTSTR lpNameBuffer, // name buffer
PULONG nSize // size of name buffer
);

In the ManagedCode.cs file, notice the ‘TODO’ comment near the

beginning, instructing you to add the declaration for a method that is used to
call GetUserNameEx. Add the declaration for the method, including the
DllImport attribute. Your method should also be named GetUserNameEx.
Some key information you need in order to add the declaration is listed in
the following table.
Information Value

DLL containing the GetUserNameEx function secur32.dll

Character set to use CharSet.Auto

For information about the managed data types to use in your method
declaration, see Marshaling earlier in this module. Notice that you can use
the task list tab in the lower-left hand pane to find the ‘TODO’ comments.
Click View, click Show Tasks, and then click All if the ‘TODO’ comments
do not appear in the task list.
18 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

! Add the DllImport attribute for the method used to display the user
name
• MessageBox is the Win32 API to be called. The signature for this function
is as follows:
int MessageBox(
HWND hWnd, // handle to owner window
LPCTSTR lpText, // text in message box
LPCTSTR lpCaption, // message box title
UINT uType // message box style);

In the ManagedCode.cs file, notice the next ‘TODO’ comment near the
beginning, instructing you to add the declaration for a method that is used to
call MessageBox. Add the declaration for the method, including the
DllImport attribute. Your method should also be named MessageBox.
Some key information you need in order to add the declaration is listed in
the following table.
Information Value

DLL containing the MessageBox function user32.dll

Character set to use CharSet.Auto

For information about the managed data types to use in your method
declaration, see Marshaling earlier in this module. Notice that the strings
passed to MessageBox are input-only parameters.

! Implement the methods that call unmanaged code

1. Scroll down in the ManagedCode.cs file to find the next ‘TODO’ comment
near the end of the file in the buttonRetrieveUserName_Click method.
The comment instructs you to add the code to retrieve the user name and
display it in a message box. Replace the comment with a call to
GetUserNameEx followed by a call to MessageBox.
The SamCompatibleNameFormat constant represents the format of the
username that will be returned from GetUserNameEx. Note that
GetUserNameEx returns a non-zero value if it succeeds. Otherwise it
returns a value of zero.
For the uType parameter to MessageBox, you should pass in
(uint)MessageBoxIcon.Information if GetUserNameEx succeeds, or
(uint)MessageBoxIcon.Error if GetUserNameEx fails. MessageBox
returns a value for the button clicked on the message box, but this should
not affect the application.
2. Scroll down to the catch block to find the next ‘TODO’ comment
instructing you to add a MessageBox call to report the exception as an error.
Replace the comment with a call to MessageBox after the exception
message is created. Pass in (uint)MessageBoxIcon.Error for the uType
parameter.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 19

! Build and test your application

1. On the File menu, click Save All.
2. On the Build menu, click Build Solution. Your application should build
successfully. The following statement should appear as the last line of the
output window:
Build: 1 succeeded, 0 failed, 0 skipped.

3. On the Debug menu, click Start, and then click Retrieve User Name. The
user name should be displayed in a message box. Click OK to dismiss the
message box.
4. To close the application, click Exit.
20 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

" Calling COM Objects from Managed Code

Topic Objective
To introduce how COM
objects are exposed to
managed code. ! Runtime Callable Wrappers
Lead-in ! Generating Runtime Callable Wrappers
In this section you will learn
how to expose COM objects ! Threading Models
to managed code by using
runtime callable wrappers. ! Signature Translation and Error Handling
! Marshaling
! Performance and Security Issues
! Best Practices

*ILLEGAL FOR NON-TRAINER USE**

COM objects are exposed to managed code by creating runtime callable
wrappers for the objects. The purpose of the wrappers is to marshal calls
between a .NET Framework client and a COM object.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 21

Runtime Callable Wrappers

Topic Objective
To describe the purpose of
runtime callable wrappers.
Lead-in
The primary goal of runtime
callable wrappers is to hide
the differences between the
managed and unmanaged
programming models.

*ILLEGAL FOR NON-TRAINER USE**

In order to call a COM object, the runtime uses a runtime callable wrapper.
Runtime callable wrappers contain all of the information needed to call the
COM object. The runtime callable wrapper maintains a cache of interface
pointers on the COM object it wraps and releases its reference on the COM
object when the wrapper is no longer needed. The runtime performs garbage
collection on the runtime callable wrapper after the COM object has been
released.
One of the primary functions of the runtime callable wrapper is to marshal data
between managed and unmanaged code. The runtime callable wrapper provides
marshaling for method arguments and method return values whenever the client
and server have different representations of the data passed between them. For
example, when a .NET Framework client passes a String type as part of an
argument to a managed object, the wrapper converts the String type to a BSTR
type. Should the COM object return a BSTR type to its managed caller, the
caller receives a String type. Both the client and the server send and receive
data types that are familiar to each of them. Some other types require no
conversion. For instance, a standard wrapper will always pass a 4-byte integer
between managed and unmanaged code without converting the type.
The runtime callable wrapper implements the interfaces that the COM object
implements and exposes the methods, properties, and events from the object’s
interfaces. In the illustration, the wrapper exposes the INew interface and all its
methods and properties to the client, but consumes the IUnknown and
IDispatch interfaces. The IUnknown interface is used by the runtime to
identify the COM object, provide type coercion, and control lifetime
management. The runtime distinguishes between COM objects by comparing
the value of the IUnknown interface for each object. The wrapper uses the
QueryInterface method to get and hold a reference to an unmanaged object.
The reference is retained until the runtime performs garbage collection on the
wrapper. The wrapper releases the unmanaged object during garbage collection.
22 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

The runtime callable wrapper also consumes the interfaces listed in the
following table.
Interface Description

IErrorInfo If the COM object being wrapped implements the IErrorInfo

interface, the exceptions generated by the wrapper contain the
information provided by the interface
IProvideClassInfo If the COM object being wrapped implements the
IProvideClassInfo interface, the wrapper extracts the type
information from this interface to provide better type identity
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 23

Generating Runtime Callable Wrappers

Topic Objective
To define the three ways to
generate runtime callable
wrappers. ! Runtime Callable Wrappers Are Generated in One of
Three Ways:
Lead-in
Runtime callable wrappers # Adding a reference to a COM component in a
are generated in one of Visual Studio .NET project
three ways.
# Employing the Type Library Importer
# Creating custom wrappers

*ILLEGAL FOR NON-TRAINER USE**

Runtime callable wrappers are generated in one of three ways:
Delivery Tip
You may want to create an ! Adding a reference to a COM component in a Visual Studio .NET project
RCW and use the Microsoft
Intermediate Language This automatically converts COM types in a type library to metadata in an
disassembler to show what assembly.
the metadata looks like. ! By using the Type Library Importer
This provides command-line switches to adjust metadata in the resulting
assembly file, imports types from an existing type library, and generates an
assembly and a namespace.
! Creating custom wrappers
As a less-desirable option, you can create type definitions. This requires
advanced programming skills.

Visual Studio .NET generates an assembly containing metadata when you add a
reference to a specific type library.

! To add a reference to a type library in Visual Studio .NET

1. Install the COM DLL or EXE file manually on your computer and use
Regsrv32.exe to add a component to the registry, unless a Microsoft
Windows installation program performs the installation for you.
2. In Visual Studio .NET, on the Project menu, click Add Reference.
3. Click the COM tab.
4. In the Component Name list, double-click the type library, and then click
OK.
24 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

The Type Library Importer (Tlbimp.exe) is a command-line tool that converts

the coclasses and interfaces contained in a COM type library to metadata. This
tool creates an assembly and namespace for the type information automatically.
After the metadata of a class is available, managed clients can create an
instance of the COM type and call its methods, as if it were a .NET Framework
instance. The Type Library Importer converts an entire type library to metadata
at once but cannot generate type information for a subset of the types defined in
a type library.

! To generate an assembly from a type library

• To produce the Loanlib.dll assembly in the Loanlib namespace, type the
following command:
tlbimp Loanlib.tlb

Adding the /out: switch produces an assembly with an altered name, such as
Loanlib_RCW.dll. Altering the runtime callable wrapper assembly name can
help distinguish it from the original COM DLL. The following example uses
the /out: switch of the Type Library Importer to alter the generated assembly’s
name:
tlbimp Loanlib.dll /out: Loanlib_RCW.dll

When a type library is unavailable or incorrect, one option is to create a

duplicate definition of the class or interface in managed source code. You then
compile the source code with a compiler that targets the runtime in order to
produce metadata in an assembly.
To define COM types manually, you must have access to the following items:
! Precise descriptions of the coclasses and interfaces being defined.
! A compiler, such as the C# compiler, that can generate the appropriate .NET
Framework class definitions.
! Knowledge of the rules for conversion from a type library to an assembly.

Writing a custom wrapper is an advanced technique that you seldom perform.

However, if you need to create custom wrappers, there are two methods to do
this:
! If you have access to the Interface Definition Language (IDL) source, you
can modify the source by applying type library file attributes and import the
type library.
! You can apply interop-specific attributes to imported types and generate a
new assembly.

For additional information on generating a custom wrapper, see “Customizing

Standard Wrappers” in the .NET Framework SDK documentation.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 25

Demonstration: Using the Type Library Importer

Topic Objective
To demonstrate how to use
the Type Library Importer to
convert the type definitions
found within a COM type
library into equivalent
definitions in a .NET
assembly.
Lead-in
In this demonstration you
will learn how to use the
Type Library Importer to
convert the type definitions
found within a COM type
library into equivalent
definitions in a .NET
assembly.

*ILLEGAL FOR NON-TRAINER USE**

The Type Library Importer (Tlbimp.exe) can be used to convert the coclasses
and interfaces found within a COM type library into equivalent definitions in a
.NET assembly. The output of the Type Library Importer is an assembly that
contains metadata for the types defined within the original type library. The
Type Library Importer performs the following tasks:
! Converts unmanaged COM coclasses to C# classes with a constructor
(without parameters) and no other methods.
! Converts unmanaged COM vtable interfaces to C# interfaces.
! Converts unmanaged COM structures to C# structures with public fields.

The syntax for using the Type Library Importer is as follows:

tlbimp inputFile [options]

In the previous example, inputFile is the name of the file that contains the COM
type library. This file can be either a stand-alone type library (.TLB) file or a
DLL. The following command imports a type library file and generates a .NET
assembly named myTest.dll:
tlbimp myTest.tlb
26 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

The /out: option specifies the name of the assembly that is created as a result of
running the Type Library Importer. The following command creates
myNewTest as a DLL:
tlbimp myTest.tlb /out:myNewTest.dll

If the output assembly’s file name is equivalent to the input type library’s file
name, the Type Library Importer will generate an error, because the input file
cannot be overwritten.
The /delaysign option delays signing of the assembly. The /delaysign option
must be used with the /keycontainer:, /keyfile:, or /publickey: option. For a
complete list of all the options that can be used with the Type Library Importer,
see “Type Library Importer (Tlbimp.exe)” in the .NET Framework SDK
documentation.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 27

Threading Models
Topic Objective ! COM Components Use Apartments to Synchronize Access to
To describe the threading Managed Resources
models in managed and
unmanaged code. ! Runtime Creates/Initializes Apartment When Calling a COM Object
using
using System.Threading;
System.Threading;
Lead-in
The threading models that using
using APTOBJLib;
APTOBJLib;
are supported by COM ……
components and the .NET Thread.CurrentThread.ApartmentState
Thread.CurrentThread.ApartmentState ==
Framework are different. ApartmentState.STA;
ApartmentState.STA;
While managed objects use AptSimple
AptSimple obj
obj == new
new AptSimple
AptSimple ();
();
synchronized regions… obj.Counter
obj.Counter == 1;
1;
! To ensure that the main thread of an application is STA
……
[STAThread]
[STAThread]
static
static void
void Main()
Main()
……

*ILLEGAL FOR NON-TRAINER USE**

COM components use apartments to synchronize access to managed resources.
In contrast, managed objects use synchronized regions; synchronization
primitives such as mutexes, locks, and completion ports; and synchronized
contexts to ensure that all shared resources are used in a thread-safe manner.
For interoperability, the common language runtime creates and initializes an
apartment when calling a COM object. A managed thread can create and enter a
single-threaded apartment (STA) that contains only one thread, or a multi-
threaded apartment (MTA) that contains one or more threads. When a COM
apartment and a thread-generated apartment are compatible, COM permits the
calling thread to make calls directly to the COM object. If the apartments are
incompatible, COM creates a compatible apartment and marshals all calls
through a proxy in the new apartment.
On the first call to unmanaged code, the runtime calls CoInitializeEx to
initialize the COM apartment as either an MTA or an STA. You can control the
type of apartment created by setting the System.Threading.ApartmentState
property on the thread to MTA, STA, or Unknown. As long as the proxy and
stub are registered or the type library is registered, you do not have to set this
property. If neither the proxy and stub nor the type library is registered, an
InvalidCastException can occur when calling a COM object from managed
code.
28 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

The following table lists the ApartmentState enumeration values and shows
the comparable COM apartment initialization call.
ApartmentState
enumeration value COM apartment initialization

MTA CoInitializeEx(NULL, COINIT_MULTITHREADED)

STA CoIntializeEx(NULL,
COINIT_APARTMENTTHREADED)
Unknown CoInitializeEx(NULL, COINIT_MULTITHREADED)

Whenever the COM object and the managed thread are in incompatible
apartments, all calls on the object are made through a COM created proxy. For
example, calls between Windows Forms controls whose COM objects must
reside in an STA and managed code whose thread’s ApartmentState is MTA.
The following example shows how to create an STA apartment-threaded COM
object, AptSimple, from managed code:
using System.Threading;
using APTOBJLib;
…
AptSimple obj = new AptSimple ();
obj.Counter = 1;

To eliminate the use of proxies and stubs and significantly enhance

performance, set the ApartmentState on the thread before creating the object,
as shown in the following example:
using System.Threading;
using APTOBJLib;
…
Thread.CurrentThread.ApartmentState = ApartmentState.STA;
AptSimple obj = new AptSimple ();
obj.Counter = 1;
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 29

A thread can only initialize a COM apartment once. Since the runtime
initializes the apartment before making the very first call to unmanaged code on
that thread, you should set the ApartmentState as early as possible. Changing
the ApartmentState after the apartment has been initialized has no effect. You
can neither un-initialize nor re-initialize an apartment. In some situations, the
thread may already have called into unmanaged code before the ApartmentState
could be set. In such cases, you cannot change the apartment type after the
thread is initialized. Your only option is to create a new thread.
As an alternative to setting the ApartmentState enumeration, you can apply
the System.STAThreadAttribute or System.MTAThreadAttribute to the
main entry point of the application. By applying these attributes you ensure that
the main thread of an application is in the proper state. For example:
…
[STAThread]
static void Main()
…

After setting the apartment state, you can check the state programmatically, as
in the following example:
Thread.CurrentThread.ApartmentState = ApartmentState.STA;
if (Thread.CurrentThread.ApartmentState == ApartmentState.STA)
//STA apartment state
else
//incompatible apartment state
30 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

Signature Translation and Error Handling

Topic Objective
To describe how signature
translation works.
Lead-in
Signature translation is the
mechanism by which
managed return values are
converted into COM
HRESULTs.

*ILLEGAL FOR NON-TRAINER USE**

COM components accept COM data types and return HRESULTs. However,
classes in the .NET Framework do not use HRESULTs. In order to satisfy both
models, every method of a managed type has a .NET Framework signature and
an implied COM signature.
When COM interoperability services imports a COM type, it produces a
.NET Framework method signature equivalent to the original COM method
signature. This is referred to as signature translation. During signature
translation, COM parameters, return values, and HRESULTs are mapped to
corresponding entities in the .NET Framework method signature, as shown in
the illustration on the slide.
When the COM object returns an error HRESULT, the runtime converts the
HRESULT to an exception, which is thrown to the caller. The type of exception
that is generated depends on the error returned from the COM object. Note that
any non-error HRESULTs will be lost in this conversion. For example, if a
COM object returns any success HRESULT other than S_OK, such as
S_FALSE, no exception is thrown, but the managed caller does not receive the
HRESULT. You must manually generate the runtime callable wrappers to
avoid this issue.
A managed signature is converted to an unmanaged signature by changing the
managed return value to an [out, retval] parameter and changing the type of the
unmanaged return value to HRESULT. The COM signature returns an
HRESULT and has an additional output parameter for the return value. The
return value from the managed implementation always returns as an [out,
retval] parameter added to the end of the unmanaged signature, whereas the
unmanaged signature always returns an HRESULT. If the managed method has
a void return, the runtime omits the [out, retval] parameter.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 31

Under some circumstances, it is preferable to leave the managed signature

unchanged. You can use the PreserveSig attribute to do this. The following
examples show the translation from a managed signature to an unmanaged
signature.
Managed signature:
[PreserveSig] short DoSomething(short i);

Unmanaged signature:
short DoSomething ([in] short i);
32 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

Marshaling
Topic Objective
To describe how COM types ! Wrappers perform data marshaling
relate to .NET Framework # Support for marshaling data to and from COM almost
types and classes. always provides the correct marshaling behavior
Lead-in
Types used in COM have ! Table shows corresponding COM and C# types
corresponding .NET ! MarshalAsAttribute to change the marshaling behavior
Framework built-in value
types or classes.
public
public void
void M1
M1
([MarshalAs(UnmanagedType.LPWStr)]String
([MarshalAs(UnmanagedType.LPWStr)]String msg);
msg);
Direct students to the
Student Notes and explain
! Two ways to customize the RCW to handle types
that the table that is referred # Edit the interop assembly
to in the slide may be found
in the Student Notes. # Create a wrapper manually

*ILLEGAL FOR NON-TRAINER USE**

When marshaling data between managed and unmanaged code, the interop
marshaler must recognize the representations of the data being passed.
! For blittable types, managed and unmanaged representations are always the
same: a 4-byte integer is always marshaled to a 4-byte integer. The interop
marshaler uses the managed signature to determine the data representation.
! For non-blittable types, the interop marshaler recognizes the managed
representation from its method signature, but is unable to do the same for
the unmanaged representation. To marshal non-blittable types, you can use
one of the following techniques:
• Allow the marshaler to infer the representation from the managed
representation.
• Supply the unmanaged data representation explicitly.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 33

The following table shows data types used in COM and their corresponding
.NET Framework built-in value types or classes. Any type not explicitly
identified in this table is converted to an Int32 system type.
COM value type COM reference type C# Data Type

bool bool * int

char, small char *, small * System.SByte
short short * short
long, int long *, int * int
Hyper hyper * long
unsigned char, byte unsigned char *, byte * byte
wchar_t, unsigned short wchar_t *, unsigned short * ushort
unsigned long, unsigned int unsigned long *, unsigned int * uint
unsigned hyper unsigned hyper * ulong
float float * float
double double * double
VARIANT_BOOL VARIANT_BOOL * bool
void * void ** System.IntPtr
HRESULT HRESULT * System.IntPtr
SCODE SCODE * int
BSTR BSTR * string
LPSTR or [string, …] LPSTR * string
char *
LPWSTR or [string, …] LPWSTR * string
wchar_t *
VARIANT VARIANT * object
DECIMAL DECIMAL * System.Decimal
DATE DATE * System.DateTime
GUID GUID * System.Guid
CURRENCY CURRENCY * System.Decimal
IUnknown * IUnknown ** object
IDispatch * IDispatch ** object
SAFEARRAY(type) SAFEARRAY(type) * type[ ]
34 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

The following table lists COM value and reference types that convert to
corresponding element types. For example, a COM coclass automatically maps
to a managed class with the same name.
COM value type COM Reference type Element type

typedef BaseType ByRef BaseType BaseType

MyType
MyStruct ByRef VALUETYPE<MyStruct> valuetype<MyStruct>
MyEnum ByRef VALUETYPE<MyEnum> valuetype<MyEnum>
MyInterface * ByRef CLASS <MyInterface> Class<MyInterface>
MyCoClass ByRef CLASS <_Class> class <_Class>

You can apply the System.Runtime.InteropServices.MarshalAsAttribute to

a method parameter, class field, or return value to change the marshaling
behavior. For example, a string is converted to a BSTR type when marshaled
from managed to unmanaged code, unless you explicitly apply the
MarshalAsAttribute to marshal the string to another type, such as LPWSTR.
You can apply this attribute to a parameter, field, or return value within the
source of the type definition, as shown in the following examples where it is
specified that msg is to be marshaled as a null-terminated buffer of Unicode
characters (LPWStr).
Apply the MarshalAsAttribute to a parameter:
public void M1
([MarshalAs(UnmanagedType.LPWStr)]String msg);

Apply the MarshalAsAttribute to a field within a class:

class MsgText {
[MarshalAs(UnmanagedType.LPWStr)] Public String msg;
}

Apply the MarshalAsAttribute to a return value:

[return: MarshalAs(UnmanagedType.LPWStr)]
public String GetMessage();
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 35

Although the import process generally produces accurate interop assemblies,

there are cases when you can (or must) modify the interop assembly to produce
a custom RCW.
There are several reasons why you might customize an RCW, such as:
! One or more types require additional marshaling information.
! A type library contains many specialized types that are unrecognizable to
the marshaler.
! A large type library can include types that are unnecessary for an
application.
You can eliminate the need to deploy unnecessary types by creating an
interop assembly from managed source code.

If you must customize the runtime callable wrapper with additional or different
marshaling instructions, you can either:
1. Edit the interop assembly, searching for problematic syntax and replacing it
with alternative syntax.
This option is best for minor marshaling changes.
2. Create a wrapper manually, based on an existing Interface Definition
Language (IDL) file or type library.
Declaring COM types manually is a difficult activity that requires working
knowledge of the Type Library Importer (Tlbimp.exe), the default behavior
of the interop marshaler, and COM. This approach is best used when you
have an entire library of specialized types or require the RCW source code.

For more information about implementing these choices, see the .NET
Framework Software Development Kit (SDK) documentation.
36 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

Performance and Security Issues

Topic Objective
To list some performance
issues that arise from ! Recognize that transitions that occur when managed
running unmanaged code code must interact with unmanaged code result in an
from managed code. overhead of 10 to 40 instructions per call.
Lead-in # Limit the number of transitions that appear in your code
Running unmanaged code
from managed code # Instead, use API calls that perform several actions
decreases the performance at once
of your application.
! Eliminate the creation of the proxy and stub by setting
the ApartmentState on the thread before creating a
COM object
! For trusted code, suppress security checks that are
performed when managed code calls unmanaged code

*ILLEGAL FOR NON-TRAINER USE**

Transitions occur when managed code must interact with unmanaged code. A
slight overhead is associated with every transition. These overheads require 10
to 40 instructions per call. The best practice is to limit the number of transitions
that appear in your code. If you must use transitions, use API calls that perform
several actions from the same call instead of ones that only perform few actions
and must be repeatedly called.
Threading models that are used in managed and unmanaged code affect the
performance of applications. Whenever a COM object and a managed thread
are in incompatible apartments, all calls on the object are made through a
COM-created proxy. To eliminate the use of proxies and stubs, and
significantly enhance performance, set the ApartmentState on the thread
before creating the object.
Security checks that are performed when unmanaged code is run, also lead to a
decrease in application performance. You can suppress these security checks
and increase the performance of your application.
When managed code calls unmanaged COM code by using COM
interoperability services, a demand for the UnmanagedCode permission is
made to ensure that all callers have the necessary permission to allow the call to
proceed. You can suppress the demand for the UnmanagedCode permission at
run time by using the SuppressUnmanagedCodeSecurityAttribute attribute.
The demand for the UnmanagedCode permission will still occur at link time.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 37

The SuppressUnmanagedCodeSecurityAttribute attribute helps improve

code performance by suppressing asserts and demands at run time. These run
time asserts and demands are the usual security checks performed when calling
unmanaged code. Only code that has been granted the UnmanagedCode
permission can use the SuppressUnmanagedCodeSecurityAttribute attribute,
however. Using this attribute in a class or module applies to all methods
contained in the class or module.
When you use the SuppressUnmanagedCodeSecurityAttribute attribute in a
class, code that does not have permission to access unmanaged code can call
methods in the class to access unmanaged code. Therefore, you must make sure
that when you use the SuppressUnmanagedCodeSecurityAttribute attribute,
you write secure code. Otherwise, your code can be misused by malicious code.
38 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

Best Practices
Topic Objective
To list some best practices
to be followed when calling
COM components from ! The MSIL Disassembler can be used on the generated
managed code. assembly to determine the exact names of the
namespace and classes that are generated
Lead-in
Let’s look at some best ! Any parameter passed by reference in C++ or
practices that you should Visual Basic 6.0 will generate a parameter that needs
use when calling COM to be passed by using the ref keyword in C#
components from managed
code.

*ILLEGAL FOR NON-TRAINER USE**

If you create your runtime callable wrapper assembly by adding a reference to a
COM object in Visual Studio .NET or by using the Type Library Importer, the
namespace and class names that are generated might not always be obvious. To
view these names, you can run the MSIL Disassembler on the particular
assembly. If you create the runtime callable wrapper assembly with
Visual Studio .NET, you must attempt to build the project once to generate the
assembly.
Parameters passed by reference in unmanaged code frequently require the use
of the ref keyword when that code is called by using C#. For C or C++, this
includes most parameters passed as pointers. For Visual Basic 6.0, keep in mind
that, by default, all parameters are passed by reference. The most notable
exception to this is for passing string types, which can usually be passed as
String or StringBuilder objects from managed code. For an example in C or
C++ of passing a string type, see Marshaling in this module.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 39

Lab 15.2: Calling COM Objects

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will call a
COM object from managed
code.

*ILLEGAL FOR NON-TRAINER USE**

Objectives
After completing this lab, you will be able to call a COM object from managed
code.

Estimated time to complete this lab: 30 minutes

40 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

Exercise 1
Calling a COM Object From Managed Code
In this exercise, you will call a COM object from managed code. This includes
registering the COM DLL, adding a reference to the COM object in a
Visual Studio .NET project, and then adding code to call the COM object.

Important To use Microsoft Visual Studio .NET tools within a command

! Register the COM object

1. At the command prompt, change the current folder to <install folder>\Labs\
Lab15\Lab15.2\Starter.
2. To register the COM object, run regsvr32 VBUnmanagedCalculator.dll.
3. A dialog box appears informing you that the registration succeeded. Click
OK to dismiss the dialog box.

! Open the Visual Studio .NET project for this exercise and examine the
application UI
1. In Windows Explorer, move to <install folder>\Labs\Lab15\Lab15.2\
Starter.
2. Double-click CallingComFromDotNet.csproj to open the project for this
exercise in Visual Studio .NET.
3. In the Solution Explorer pane, double click CalcUI.cs. The UI design for
the Windows Forms application appears. Examine the UI for a moment to
become familiar with it.
4. Press F7 to edit the code that implements the Windows Form application.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 41

! Add the reference to the COM object and attempt to build the project
1. On the Project menu, click Add Reference.
2. In the Add Reference dialog box, click the COM tab. In the list of
registered COM objects, click VBUnmanagedCalculator.
3. To add VBUnmanagedCalculator to the Selected Components window,
click Select.
4. To add the reference, click OK. Notice that the VBUnmanagedCalculator
DLL is added to the project references.
5. On the Build menu, click Build Solution. Your application does not build
successfully yet, but the runtime callable wrapper assembly for the
VBUnmanagedCalculator.dll is generated.
6. In a Visual Studio .NET Command Prompt window, change the current
folder to <install folder>\Labs\Lab15\Lab15.2\ Starter\bin\Debug.
7. To view the metadata in the runtime callable wrapper assembly, at the
command prompt, type ildasm /adv Interop.VBUnmanagedCalculator.dll
Use the MSIL Disassembler to view the namespace and classes created for
the COM object.

! Modify the code in the project to call the COM object

1. In the CalcUI.cs file, find the first ‘TODO’ comment that instructs you to
add a using statement for VBUnmanagedCalculator. Add the correct using
statement. Notice that you can use the Task List tab in the lower-left hand
pane to find the ‘TODO’ comments. Click View, select Show Tasks, and
then click All if the ‘TODO’ comments do not appear in the task list.
2. Find the next ‘TODO’ comment that instructs you to instantiate a
CalcEngine object. Add the code to instantiate a CalcEngine object and
assign it to the calcEngine private member variable.
3. Scroll down to the next ‘TODO’ comment that instructs you to call
GetVersion in CalcEngine. Add the code to make the call described and
assign the results of the call to the VersionInfo text box.
4. Scroll down to the KeyDate_Click method. Complete the code in this
method by replacing the ‘TODO’ comment with code to obtain the date by
calling the GetDate method in CalcEngine and assign the results of the call
to the OutputDisplay text box. Then, add code to reset the engine for the
next equation by calling the CalcReset method in CalcEngine.
5. In the KeyClear_Click method, complete the code by replacing the
‘TODO’ comment with code that calls the CalcReset method in
CalcEngine and clears the OutputDisplay text box.
42 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

! Build and test your application

3. On the Debug menu, click Start. When the calculator appears, check the
version number. It should read “Calculator – VB6 Unmanaged Component”.
Enter some equations to test the application.
4. Close the application.

Note If you wish to test the solution project, you will first need to follow the
steps in the “Register the COM object”, “Open the Visual Studio .NET project
for this exercise and examine the application UI”, and “Add the reference to the
COM object and attempt to build the project” procedures above.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 43

" Calling .NET Objects from COM Objects

Topic Objective
To introduce how COM
callable wrappers are used ! COM Callable Wrappers
to expose .NET Framework
classes to COM clients. ! The Export Process
Lead-in ! Registering a .NET Framework Class with the System
In this section, you will learn
how to create COM callable
Registry
wrappers to use .NET ! Using the ClassInterfaceAttribute
Framework types for a COM
client. ! Using .NET Framework Types from COM
! Managed and Unmanaged Events
! Best Practices

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework allows existing COM applications to use managed code
transparently by generating COM callable wrappers for .NET Framework
classes. These wrappers are generated at run time. COM callable wrappers are
proxy objects that are generated from the metadata that is stored in an assembly,
so COM applications can use the .NET Framework classes in the same manner
as they would use COM components.
44 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

COM Callable Wrappers

Topic Objective
To describe how the runtime
uses COM callable
wrappers to expose
managed classes to COM
clients.
Lead-in
To allow COM clients to use
a managed class, the .NET
Framework creates a COM
callable wrapper.

*ILLEGAL FOR NON-TRAINER USE**

COM clients cannot reference a .NET Framework object directly. When a COM
client calls a .NET Framework object, the common language runtime creates
the managed object and a proxy for the managed object called the COM
callable wrapper.
The purpose of a COM callable wrapper is to marshal calls between managed
and unmanaged code, and to manage the identity and lifetime of the managed
object it wraps. COM callable wrappers are invisible to other classes running
within the .NET Framework. Unlike the managed object it wraps, the COM
callable wrapper is allocated memory from a non-collected heap. This makes it
possible for COM clients to reference the wrapper directly.
COM callable wrappers are reference-counted in the traditional COM fashion.
When the reference count on the wrapper reaches zero, the wrapper releases its
reference on the managed object. A managed object with no remaining
references is collected during the next garbage-collection cycle.
The runtime creates one COM callable wrapper for a managed object,
regardless of the number of COM clients requesting its services. The COM
callable wrapper, in turn, holds a single reference to the managed object that
implements the interface. Both COM clients and .NET Framework clients can
make requests on the same managed object simultaneously.
When you compile your managed code into an assembly, metadata describing
each type in the assembly is generated. The Type Library Exporter can be used
to create a type library file from the metadata for your assembly. COM clients
can then import the type library and use the managed object like any other
COM object. When the COM client tries to create and access a managed object
from the assembly, the runtime uses the assembly’s metadata to generate a
COM callable wrapper. The wrapper marshals the call between the COM client
and the managed object.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 45

You can customize the COM callable wrapper by applying interop-specific

attributes to your managed source code and compiling the source code into an
assembly.

Caution If you plan to export a managed object, be aware that the COM client
determines the apartment of the object. A managed object called by a COM
client initialized in an MTA must ensure thread safety.
46 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

Demonstration: Using the Type Library Exporter

Topic Objective
To describe the use of the
Type Library Exporter.
Lead-in
The Type Library Exporter is
a command-line tool that
exports the type information
to a type library so that it
can be used from a COM
client.

*ILLEGAL FOR NON-TRAINER USE**

The Type Library Exporter (Tlbexp.exe ) is a command-line tool that builds a
type library for .NET Framework classes so that they can be used from
unmanaged clients. The Type Library Exporter uses the metadata that is stored
in the assembly to generate the type library. The type library contains
definitions of the types defined in an assembly. Applications that use
unmanaged code can use the generated type library to bind to the .NET
Framework types defined in the assembly.

Note You cannot use the Type Library Exporter to produce a type library from
an assembly that was imported by using the Type Library Importer
(Tlbimp.exe). Instead, you should refer to the original type library that was
imported with the Type Library Importer. You can export a type library from an
assembly that references assemblies that were imported by using the Type
Library Importer.

You must use the Type Library Exporter to generate a type library for an entire
assembly and not just a subset of the types that are defined in the assembly. A
single assembly may cause several type libraries to be generated, and these type
library files are placed in the current working directory or the directory
specified for the output file when running the Type Library Exporter.
The Type Library Exporter generates a type library but does not register the
types it exports with the system registry. To generate and register a type library
with COM, use the Assembly Registration tool (Regasm.exe). For information
about using the Assembly Registration tool to register a type library, see
Registering a .NET Framework class with the System Registry in this module.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 47

The Export Process

Topic Objective
To describe how the export ! Every public class in an assembly is converted to a
process converts classes coclass in a type library
and interfaces.
! Interfaces that are explicitly implemented are exported
Lead-in to the type library
The export process creates
definitions for the classes Managed Code Type Library
and interfaces that are
defined in an assembly. public
public interface
interface IShape
IShape [[ uuid(…),
uuid(…), dual,
dual, odl,
odl, oleautomation
oleautomation ]]
{{
interface
interface IShape
IShape :: IDispatch
IDispatch {{
void Draw();
void Draw(); HRESULT
HRESULT Draw();
Draw();
void
void Move(int
Move(int x,
x, int
int y);
y); HRESULT
HRESULT Move(int
Move(int x,
x, int
int y);
y);
}}
}}
class
class Circle
Circle :: IShape
IShape [[ uuid(…)
uuid(…) ]]
{{
coclass
coclass Circle
Circle {{
void Draw();
void Draw(); interface
interface IShape;
IShape;
void
void Move(int
Move(int x,
x, int
int y);
y); }}
void
void Enlarge(int
Enlarge(int x);
x); }}
}}

*ILLEGAL FOR NON-TRAINER USE**

When you run the Type Library Exporter on your assembly to generate a type
library, the export process converts the classes and interfaces defined in your
assembly, and creates representations for them in the type library.
The export process converts each public class in an assembly to a coclass in a
type library, and gives the coclass the same name as the managed class. All the
interfaces that are explicitly implemented by the managed class are exported to
the type library. Methods and properties are not exported.
When the class in the example in the slide is exported, the type library will
contain a representation for the IShape interface and a coclass definition for the
Circle class. The Draw, Move, and Enlarge methods of the Circle class will
not be exported.
When an assembly is exported, all managed interfaces and their methods and
properties are converted to COM interfaces. By default, the COM interface that
is generated in the type library file is a dual interface. You can use the
ClassInterfaceAttribute to determine the type of interface that is defined when
the type library is exported.
Each coclass can implement one other interface, called the class interface,
which the export process generates automatically. The class interface exposes
all methods and properties available in the original managed class, thereby
enabling COM clients to access them by calling through the class interface.
48 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

Registering a .NET Framework Class with the System Registry

Topic Objective
To describe the procedure
for registering a .NET ! To register a .NET Framework class with the system registry, use
Framework class with the the Assembly Registration tool (Regasm.exe)
system registry. ! Registering a .NET Framework class creates the following entries in
Lead-in the system registry:
Before you can use a .NET # The CLSID of the .NET Framework class under the
Framework class from Hkey_Classes_Root\CLSID registry key
unmanaged code, you must # Two sub keys: Implemented Categories and InprocServer32 under
register the class with the the HKCR\CLSID\<class ID> key
system registry.
! The default value of the HKCR\CLSID\<class ID> key is set to the
ProgID of the class
! The default value of the InprocServer32 is set to the name of the
DLL that contains the common language runtime (Mscoree.dll)

*ILLEGAL FOR NON-TRAINER USE**

Before you can use a .NET Framework class from unmanaged code, you must
register the class with the system registry. To register a .NET Framework class
with the system registry, you use the command-line Assembly Registration tool
(Regasm.exe). The Assembly Registration tool adds information about the class
to the system registry so COM clients can use the .NET Framework class
transparently. You can also use the RegistrationServices class from within
your managed code, to register your .NET Framework class with the system
registry.
When you register a .NET Framework class, the following entries are made in
the system registry:
! A new entry for the class identifier (CLSID) of the .NET Framework class
is created under the HKEY_CLASSES_ROOT\CLSID registry key. After
the CLSID is generated for the .NET Framework class, the Assembly
Registration tool always uses the same CLSID, regardless of the number of
times it is used on the class.
! Under the HKEY_CLASSES_ROOT\CLSID\<class ID> key, are two sub
keys: ImplementedCategories and InprocServer32. The default value of
the HKEY_CLASSES_ROOT\CLSID\<class ID> key is set to the
ProgID of the class. The default value of the InprocServer32 is set to the
name of the DLL that contains the common language runtime (Mscoree.dll).

When a COM client attempts to load the assembly in which the class is
implemented, the runtime reads the assembly value from the registry and passes
it on to the runtime assembly resolver. The assembly resolver attempts to locate
the assembly based on the assembly information, such as the name and version
number. Before the assembly resolver can locate the assembly, however, the
assembly must be signed and installed in the global assembly cache, or it must
be in the application’s root directory or a subdirectory of the application’s root
directory.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 49

Using the ClassInterfaceAttribute

Topic Objective
To describe the use of the
ClassInterfaceAttribute to
control the type of interface ! The class interface is an interface that exposes all
that is created for a public methods, properties, fields, and events that are
managed class. explicitly exposed on the .NET Framework object
Lead-in ! The [ClassInterface(ClassInterfaceType.None)] attribute
When used with a .NET prevents the class interface from being created
Framework class, the
ClassInterfaceAttribute ! The [ClassInterface(ClassInterfaceType.AutoDispatch)]
can be used to control and attribute creates a dispatch interface
modify the type of interface
that is generated when that ! The [ClassInterface(ClassInterfaceType.AutoDual)]
.NET Framework class is attribute creates a dual interface
exported.

*ILLEGAL FOR NON-TRAINER USE**

The class interface is an interface that exposes all public methods, properties,
fields, and events that are explicitly exposed on a .NET Framework object. This
interface can be a dual or dispatch-only interface. The class interface receives
the name of the .NET Framework class, preceded by an underscore.
When you use the Type Library Exporter to generate a type library for a
managed class, a dispatch-only interface for each class you export is created by
default. You can use the ClassInterfaceAttribute with your class to prevent or
modify the automatic creation of this interface. When you use the
ClassInterfaceAttribute, you must add the Sytem.Runtime.InteropServices
namespace to your code.
You use the ClassInterfaceAttribute and pass the value
ClassInterfaceType.None to the constructor, to prevent the class interface
from being generated when the class metadata is exported to a type library, as
shown in the following example:
[ClassInterface(ClassInterfaceType.None)]
public class LoanApp : IExplicit
{
void M();
}

In the preceding example, COM clients can access the LoanApp class only
through the IExplicit interface.
50 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

To get the DISPID of an interface member at run time, COM clients can call
IDispatch.GetIdsOfNames. To invoke a method on the interface, pass the
returned DISPID as an argument to IDispatch.Invoke.
A dual interface that is automatically generated (ClassInterface.AutoDual)
might be appropriate in rare cases. However, a dual interface that is
automatically generated often creates version-related complexities. For
example, COM clients that are using the class interface of a derived class can
easily break when there are changes to the base class. When a third party
provides the base class, the layout of the class interface is out of your control.
Further, unlike a dispatch-only interface, a dual interface provides a description
of the class interface in the exported type library. Such a description encourages
late-bound clients to cache DISPIDs at run time.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 51

Using .NET Framework Types from COM

Topic Objective
To describe the procedure
for using .NET Framework ! To Use a .NET Framework Class from Unmanaged Code
types from COM clients.
Lead-in # Set a reference to the type library file that describes the
After you have generated a interferences of the .NET Framework class
type library for your .NET
assembly, you can use the
! In Visual Basic 6.0, Use the References Dialog Box to
assembly from unmanaged Set the Reference
code.
! In Visual C++ 6.0, Use the #import Directive to
Reference to the Type Library
! Create and Use Objects of the Classes That Are Defined
in the Type Library

*ILLEGAL FOR NON-TRAINER USE**

After you have exported the metadata from an assembly to a type library file,
you can use the .NET Framework classes that are implemented in the assembly
as you would create and use a COM object.

! To use a .NET Framework class that has been exported to a type

library from a Visual Basic 6.0 application
1. In Visual Studio 6.0, on the Project menu, click References.
The References dialog box appears.
2. To add the reference to your project, scroll down Available References list,
click the reference you want to add, and then click OK.
3. Create an object of the .NET Framework class (as you would create a COM
object), as shown in the following example:
Dim Server As New ExcelServer.ExcelServer

4. Use the methods and properties of the class, as shown in the following
example:
Dim Count As Integer
Count = Server.Count

To use a .NET Framework class from a Microsoft Visual C++® 6.0 application,
use the #import directive to reference the type library, as shown in the
following example:
#import "c:\Samples\SampleClassLibrary\SampleClassLib.tlb"
52 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

Managed and Unmanaged Events

Topic Objective
To understand at a high
level interoperability
between .NET and COM ! .NET event model differs from COM event model
events
# Managed events are based on delegates, whereas
Lead-in unmanaged events (in COM) are based on connection
Let’s look at how the NET points.
Framework event model
differs from the traditional ! See the .NET SDK for details on the topics:
COM event model.
# Handling Events Raised by a COM Source
# Raising Events Handled by a COM Sink

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework event model differs from the traditional COM event
model. Managed events are based on delegates, whereas unmanaged events in
COM are based on connection points. Both models are tightly coupled event
systems, because the client (event receiver) and server (event sender) must run
simultaneously.
The SDK explains in detail how to bridge the managed and unmanaged event
systems, enabling objects to send and receive events across the interoperation
boundary. Topics include Handling Events Raised by a COM Source and
Raising Events Handled by a COM Sink.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 53

Best Practices
Topic Objective
To list some best practices
when using managed
classes from COM clients. ! Define an Explicit Interface for COM Clients to Use
Rather Than Generating the Class Interface
Lead-in
When exposing managed ! Avoid Caching Dispatch Identifiers
code to COM clients, follow
the best practices listed on ! Restrict Using the Dual Interface Option for the Class
the slide. Interface

*ILLEGAL FOR NON-TRAINER USE**

When exposing managed code to COM clients, use the following best practices:
! Define an explicit interface for COM clients to use rather than generating
the class interface.
Because COM interop services generate class interfaces automatically, post-
version changes to your class can alter the layout of the class interface
exposed by the common language runtime. Since COM clients are typically
unprepared to handle changes in the layout of an interface, they break if you
change the member layout of the class.
To reduce the risk of breaking COM clients by inadvertently reordering the
interface layout, isolate all changes to the class from the interface layout by
explicitly defining interfaces.
Set the Value property of ClassInterfaceAttribute to
ClassInterfaceType.None to disengage the automatic generation of the
class interface and implement an explicit interface for the class.
! Avoid caching dispatch identifiers (DISPIDs).
Using the class interface is an acceptable option for scripted clients,
Visual Basic 6.0 clients, or any late-bound client that does not cache the
DISPIDs of interface members. DISPIDs identify interface members and
enable late binding.
For the class interface, generation of DISPIDs is based on the position of the
member in the interface. If you change the order of the member and export
the class to a type library, you will alter the DISPIDs generated in the class
interface.
54 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

To avoid breaking late-bound COM clients when using the class interface,
set the Value property of the ClassInterfaceAttribute to
ClassInterfaceType.AutoDispatch. This value implements a dispatch-only
class interface, but it omits the interface description from the type library.
Without an interface description, clients are unable to cache DISPIDs at
compile time. Although this is the default interface type for the class
interface, you can apply the attribute value explicitly.
! Restrict using the dual interface option for the class interface.
Dual interfaces enable early and late binding to interface members by COM
clients. At design time and during testing, you might find it useful to set the
class interface to dual. For a managed class and its base classes that will
never be modified, this option is also acceptable. In all other cases, avoid
setting the class interface to dual.
Module 15 (Optional): Interoperating Between Managed and Unmanaged Code 55

Review
Topic Objective
To reinforce module
objectives by reviewing
key points. ! Integration Services
Lead-in ! Platform Invoke
The review questions cover
some of the key concepts ! Calling COM Components from Managed Code
taught in the module.
! Calling .NET Objects from COM Objects

*ILLEGAL FOR NON-TRAINER USE**

1. List the steps for calling an API function that is implemented in a DLL.
Declare the API function with the static and extern C# keywords,
attach the DllImport attribute to the function specifying the name of the
DLL that exports the unmanaged function, and optionally specify
marshaling information.

2. What is pinning?
Pinning is a technique in which data, in its current memory location, is
temporarily locked to keep it from being relocated by the common
language runtime’s garbage collector.

3. List the tasks that are performed when the Type Library Importer is run on a
type library file.
The Type Library Importer converts unmanaged COM coclasses to C#
classes with a constructor (that does not have parameters) and no other
methods, converts unmanaged COM vtable interfaces to C# interfaces,
and converts unmanaged COM structures to C# structures with public
fields.

4. Which attribute must you use to suppress runtime security checks that are
preformed when managed code calls unmanaged code?
SuppressUnmanagedCodeSecurityAttribute
56 Module 15 (Optional): Interoperating Between Managed and Unmanaged Code

5. List some best practices when using .NET code from COM clients.
Define an explicit interface for COM clients to use rather than
generating the class interface, and avoid caching dispatch identifiers
(DISPIDs).

6. Which must you use to prevent the class interface from being generated?
Set the Value property of the ClassInterfaceAttribute to
ClassInterfaceType.None
Module 16 (Optional):
Using Microsoft
ADO.NET to Access
Contents
Data
Overview 1
Overview of ADO.NET 2
Connecting to a Data Source 10
Accessing Data with DataSets 12
Using Stored Procedures 26
Lab 16: Using ADO.NET to Access Data 34
Accessing Data with DataReaders 42
Binding to XML Data 50
Review 56
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, places or events is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data iii

Instructor Notes
Presentation: This module focuses on using ADO.NET to access data from various data
120 Minutes sources.
Lab: After completing this module, students will be able to:
60 Minutes
! Describe the ADO.NET object model.
! Connect to a data source by using ADO.NET.
! Retrieve data from a database by using DataReaders and DataSets.
! Display the data from a database on the client by using DataGrid controls.
! Use stored procedures to read data from a data source.
! Read data from an XML file into DataSets.

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach
this module.

Required Materials
To teach this module, you need the Microsoft® PowerPoint® file 2349B_16.ppt.

Preparation Tasks
To prepare for this module, you should:
! Read all of the materials for this module.
! Complete all of the demonstrations.
! Complete the lab.
! Go through the animation.
iv Module 16 (Optional): Using Microsoft ADO.NET to Access Data

Multimedia Presentation
This section provides multimedia presentation procedures that do not fit in the
margin notes or are not appropriate for the student notes.

Using ADO.NET to Access Data

! To present the animation
Action Say this

Start animation There are two ways to access data from a database by using
ADO.NET: by using a DataSet or by using a DataReader.
This animation demonstrates how these two methods work
and highlights their differences.
Click Start
Click DataSet The DataSet method is a disconnected way to access data
from a database.
In this method, when a user requests data from a database, the
DataAdapter object is used to create a DataSet, which is
basically a collection of data tables from the database that
also retains the relationships between these tables. Notice
that, after a DataSet is populated, it is disconnected from the
database.
To display the data from the DataSet, you set up a DataView
for the desired table. The DataView is then bound to a list-
bound control for displaying purposes. You can use any of
the three list-bound controls, DataGrid, Repeater, or
DataList, to display data.
The data in the list-bound control is then displayed on the
client.
An important point to make here is that the use of a
DataView to display data is necessary only in ASP.NET
Beta 1. From the Beta 2 version onward, you can directly
bind the DataSet to a list-bound control.
Click DataReader This method is similar to the Microsoft ActiveX® Data
Objects (ADO) way of accessing data by using recordsets.
In this method, when a user requests data from a database, the
Command object retrieves the data into a DataReader. A
DataReader is a read-only/forward-only view of the data. A
DataReader works similarly to a Recordset in ADO,
allowing you to simply loop through the records. Like the
ADO Recordset, the DataReader is connected to the
database. You must explicitly close the connection when you
are finished reading data.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data v

Module Strategy
Use the following strategy to present this module:
! Overview of ADO.NET
This section provides students with an overview of ADO.NET. The section
begins a description of the objects used when connecting to a database both
with a DataReader and a DataSet. Point out to students that there are
Microsoft SQL Server™ and ADO versions of many of these objects. After
describing the process of accessing data through a DataReader and a
DataSet, show the animation. Because students may be familiar with ADO,
this may be an ideal time to discuss some of the main differences between
ADO and ADO.NET.
When talking about using namespaces, explain their significance to the
students.
! Connecting to a Data Source
From this point onward, students will actually start working with
ADO.NET. Tell them that all of the examples in this module use
SqlConnection objects rather than OleDbConnection objects. Direct the
students to the Microsoft .NET Framework software development kit (SDK)
documentation for more information.
! Accessing Data with DataSets
ADO.NET provides two ways to access data, the DataSet and the
DataReader. This section focuses on accessing data by using the DataSet.
The DataSet represents a new concept, so spend additional time on this
section. The demonstrations actually show every aspect of data access with
ADO.NET. Go through the demonstrations carefully, and make sure that the
students understand the details.
! Using Stored Procedures
Most students who have worked with a SQL Server database and ADO will
have experience with using stored procedures. This section provides the
students with information about how to use stored procedures and
parameterized stored procedures with ADO.NET.
! Lab16: Using ADO.NET to Access Data
The lab for this module is encountered in the middle of the module. This is
because the module is long and also because the lab does not use material
from the last two sections in the module.
vi Module 16 (Optional): Using Microsoft ADO.NET to Access Data

! Accessing Data with DataReaders

This section focuses on accessing data by using a DataReader. Point out to
the students that, when they use a DataReader, the database connection is
always open. When they are finished reading data, they must explicitly close
the connection.
! Binding to XML Data
XML is fast emerging as the most popular language for exchanging data.
This section provides students with information on how to read XML data
by using ADO.NET.
Most students will already know about XML documents. However, for
students who are not familiar with XML, it will be useful to show an
example of an XML document and how it is displayed on the client.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 1

Overview
Topic Objective
To provide an overview of
the module topics and
objectives.
! Overview of ADO.NET
Lead-in ! Connecting to a Data Source
In this module, you will learn
about the data binding ! Accessing Data with DataSets
features in ASP.NET.
! Using Stored Procedures
! Accessing Data with DataReaders
! Binding to XML Data

*ILLEGAL FOR NON-TRAINER USE**

ADO.NET, offers a rich suite of data handling and data binding functions for
manipulating all types of data. ADO.NET is an evolution of the ADO data
access model that directly addresses user requirements for developing scalable
applications. It was designed specifically for the Web with scalability,
statelessness, and XML in mind.
After completing this module, you will be able to:
! Describe the ADO.NET object model.
! Connect to a data source by using ADO.NET.
! Retrieve data from a database by using DataReaders and DataSets.
! Display the data from a database on the client by DataGrid controls.
! Use stored procedures.
! Read data from an XML file into DataSets.
2 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

" Overview of ADO.NET

Topic Objective
To introduce the topics
included in this section.
! The ADO.NET Object Model
Lead-in
ASP.NET offers a new ! RecordSets vs. DataSets
means to retrieve data with
the introduction of ! Using Namespaces
ADO.NET.

*ILLEGAL FOR NON-TRAINER USE**

ADO.NET is not a revision of Microsoft® ActiveX® Data Objects (ADO), but a
new way to manipulate data that is based on disconnected data and XML.
Although ADO is an important data access tool it is connected by default, relies
on an OLE DB provider to access data, and it is entirely Component Object
Model (COM)-based.
ADO.NET has been designed to work with disconnected datasets. Disconnected
datasets reduce network traffic.
ADO.NET uses XML as the universal transmission format. This guarantees
interoperability as long as the receiving component runs on a platform where an
XML parser is available. When the transmission occurs through XML, it is no
longer necessary that the receiver be a COM object. The receiving component
has no architectural restrictions whatsoever. Any software component can share
ADO.NET data, as long as it uses the same XML schema for the format of the
transmitted data.
In this section, you will learn about ADO.NET. You will learn about the new
and modified objects in ADO.NET. You will also learn about some of the new
namespaces.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 3

The ADO.NET Object Model

Topic Objective .ASPX Page
To describe the ADO.NET
object model. DataReader
Lead-in Command
Company:
Company:
ADO.NET includes some of Northwind
NorthwindTraders
Traders
the same objects as ADO Database
(like Connection and Connection
Command), and introduces DataAdapter
new objects, such as
DataSets, DataReaders
and DataAdapters.
DataView
DataView

DataSet List-Bound
List-Bound
Control
Control
.ASPX Page

*ILLEGAL FOR NON-TRAINER USE**

ADO.NET evolved from the ADO data access model. By using ADO.NET, you
Delivery Tip can develop applications that are robust and scalable, and that can use XML.
Point out that there are ADO
and SQL Server versions of ADO.NET has some of the same objects as ADO (like the Connection and
the Connection, Command objects), and introduces new objects, such as the Dataset,
Command, DataAdapter,
DataReader, and DataAdapter.
and DataReader objects.

Connection Objects
Connection objects are used to talk to databases. They have properties, such as
DataSource, UserID, and Password, which are needed to access a particular
DataSource. Commands travel over connections, and result sets are returned in
the form of streams that can be read by DataReaders or pushed into DataSet
objects.
There are two kinds of connection objects in ADO.NET: SqlConnection and
OleDbConnection.

Command Objects
Command objects contain the information that is submitted to a database. A
command can be a stored procedure call, an update statement, or a statement
that returns results. You can also use input and output parameters and return
values. In ADO.NET, you can use two kinds of command objects:
SqlCommand and OleDbCommand.
4 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

DataReader Objects
A DataReader is somewhat synonymous with a read-only/forward-only view
of the data. The DataReader API supports flat as well as hierarchical data. A
DataReader object is returned after executing a command against a database. It
works similarly to a recordset in ADO; however the format of the returned
DataReader object is different from a recordset. For example, you may use the
DataReader to show the results of a search list in a Web page.
ADO.NET includes two types of DataReader objects: the SqlDataReader for
Microsoft SQL Server™ version 7.0 (or later) data, and the OleDbDataReader
for ADO data. The DataReader object is database-specific. The behavior of the
SqlDataReader may differ from the behavior of the OleDbDataReader and
additional DataReader objects that are introduced in the future.
You use the OleDbCommand and SqlCommand objects and the
ExecuteReader method to transfer data into a DataReader.

DataSet Objects
The DataSet object is similar to the ADO Recordset object, but more
powerful, and with one other important distinction: the DataSet is always
disconnected. The DataSet provides a rich object model to work with when
passing data between various components of an enterprise solution. The
DataSet object represents a cache of data, with database-like behavior. It
contains tables, columns, relationships, constraints, and data. Data coming from
a database, an XML file, code, or user input can be entered into DataSet objects
and converted into files, forms, or databases. The behavior of a DataSet is
completely consistent regardless of the underlying database, SQL Server or
OLE DB. As changes are made to the DataSet, they are tracked in a way
similar to the way changes are tracked in a word processing document.
The DataSet object has a collection of DataTable objects. A DataTable
represents one table of in-memory data. It contains a collection of columns that
represents the table's schema. A DataTable also contains a collection of rows,
representing the data contained in the table.
You use the OleDbDataAdapter and SqlDataAdapter objects and the Fill
method to get data into a DataSet.

DataView Objects
A DataView enables you to create different views of the data stored in a
DataTable, a capability that is often used in data-binding applications. By
using a DataView, you can expose the data in a table with different sort orders,
and you can filter the data by row state or based on a filter expression.
A DataView provides a dynamic view of data whose content, ordering, and
membership reflect changes to the underlying DataTable as they occur. This is
different from the Select method of the DataTable, which returns a DataRow
array from a table per a particular filter and/or sort order, and whose content
reflects changes to the underlying table, but whose membership and ordering
remain static. The dynamic capabilities of the DataView make it ideal for data-
binding applications.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 5

DataAdapter Object
While the DataSet object provides a tool for in-memory data storage, you need
another tool to create and initialize the various tables. This tool is the
DataAdapter object. It represents a centralized console that hides the details of
working with connections and commands. The DataAdapter object allows for
the retrieval and saving of data between a DataSet object and the source data
store. It is responsible for pulling out data from the physical store and pushing it
into data tables and relations. The DataAdapter object is also responsible for
transmitting any update, insertion, or deletion to the physical database. You can
use four command objects to make any updates: UpdateCommand,
InsertCommand, DeleteCommand, and SelectCommand.
The DataAdapter object exists in two forms: SqlDataAdapter objects and
OleDbDataAdapter objects. The data source is SQL Server for
SqlDataAdapter objects and any other OLE DB provider for
OleDbDataAdapter objects.
The following illustration shows the use of a SQLDataAdapter object to
transfer data between a SQL Server database and a DataSet object.
6 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

Multimedia: Using ADO.NET to Access Data

Topic Objective
To provide a high-level
overview of how to access
data by using ADO.NET.
Lead-in
In this animation, you will
learn about how ADO.NET
accesses data and how you
can display that data in an
ASP.NET page.

*ILLEGAL FOR NON-TRAINER USE**

In this animation, you will learn how to access data by using ADO.NET and
Delivery Tip how you can display that data in an ASP.NET page. To view the animation,
Tell students that they can
view the animation again
open the file 2349B_16A001.htm file from the Media folder.
later for themselves by
opening the
2349B_mod3.htm file from
the Media folder.

For details about how to run

and describe the animation,
see the Multimedia
Presentation section in the
Instructor Notes for this
module.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 7

Recordsets vs. DataSets

Topic Objective
To highlight the differences
between DataSets and
Feature Recordset DataSet
Recordsets.
Number of tables One table Multiple tables
Lead-in
In ADO, you used
Recordsets. Relationships Based on join Includes relationships

Moving through data Move row-by-row Navigate via

relationships
Data connections Connected or Disconnected
disconnected
Transmitting data COM marshalling Transmit XML file

*ILLEGAL FOR NON-TRAINER USE**

In ADO, the in-memory representation of database data is the recordset. In
ADO.NET, it is the DataSet. The DataSet contains a collection of tables and
knowledge of relationships between those tables. Each table contains a
collection of columns. These objects represent the schema of the DataSet. Each
table can then have multiple rows, representing the data held by the DataSet.
These rows track their original state along with their current state, so that the
DataSet tracks what kinds of changes have occurred. Additionally, the DataSet
provides persistence and de-persistence through XML.
There are important differences between recordsets and DataSets, which are
highlighted in the following table and detailed in the text that follows.
Feature Recordset DataSet

Number of tables One table Multiple tables

Relationships Based on join Includes relationships
Moving through data Move row-by-row Navigate via relationships
Data connections Connected or disconnected Disconnected
Transmitting data COM marshalling Transmit XML file

Number of Tables
An ADO recordset looks like a single table. If a recordset is to contain data
from multiple database tables, it must use a JOIN query, which assembles the
data from the various database tables into a single result table.
In contrast, an ADO.NET DataSet is a collection of one or more tables. The
tables within a data set are called data tables; specifically, they are DataTable
objects.
8 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

Relationships
Typically, a DataSet also contains relationships. A relationship within a
DataSet is analogous to a foreign-key relationship in a database. In ADO.NET,
a DataRelation represents the relationship.

Moving Through Data

In ADO.NET, the methods you use to read or modify data differ from the
programming methods you use in ADO in the following ways:
! In ADO, you scan sequentially through the rows of the recordset.
! In ADO.NET, rows are represented as collections, so you can loop through
a table as you would through any collection or access particular rows
through ordinal or primary key index. DataRelation objects maintain
information about master and detail records and provide a method that
allows you to get records related to the one you are working with. For
example, starting from the row of the Investor table for "Jose Lugo", you
can navigate to the set of rows of the Purchase table that describes the
purchases made by Jose Lugo.

Data Connections
In ADO.NET, the DataSet provides disconnected access to database data. In
ADO, the recordset can provide disconnected access, but is typically used to
provide connected access.

Transmitting Data
To transmit an ADO disconnected recordset from one component to another,
you use COM marshalling. To transmit an ADO.NET data set, you simply
transmit an XML file. Because components exchange ADO.NET datasets by
using XML, firewalls can allow datasets to pass.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 9

Using Namespaces
Topic Objective
To describe the new
namespaces used with
ADO.NET. ! Namespaces Used with ADO.NET Include:
Lead-in # System.Data
In.NET, you must specify
the namespace that you # System.Data.OleDb
want to use.
# System.Data.SqlClient
# System.Data.SqlTypes

*ILLEGAL FOR NON-TRAINER USE**

The Microsoft .NET Framework is an object-oriented system. When using
specific parts of the framework, you must include references to the appropriate
namespace.
When using ADO.NET from either Microsoft Visual Basic® or Microsoft
Visual C#™, you must reference the System.Data namespace, plus either the
System.Data.OleDb or System.Data.SqlClient namespace, depending on the
data source you choose to use. System.Data provides the code facilities, while
System.Data.OleDb and System.Data.SqlClient are the namespaces for the
two managed providers. The System.Data.Common namespace contains
classes that are shared by the .NET data providers. The System.Data.SqlTypes
namespace provides classes for native data types within SQL Server. These
classes provide a safer, faster alternative to other data types.
The following table summarizes the list of available namespaces with
ADO.NET.
Namespace Contains

System.Data Base objects and types for ADO.NET

System.Data.OleDb Managed OLE DB data store objects
System.Data.SqlClient SQL Server specific implementations of ADO.NET objects
System.Data.Common Classes shared by the .NET data providers
System.Data.SqlTypes SQL data types
10 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

Connecting to a Data Source

Topic Objective
To describe how to connect
to a data source by using
ADO.NET. ! Using SqlConnection
Lead-in
Connecting to a data source SqlConnection
SqlConnection mySqlConnection
mySqlConnection == new
new
is the first step in data SqlConnection("server=(local)\\NetSDK;!
SqlConnection("server=(local)\\NetSDK;!
access. Trusted_Connection=yes;database=northwind");
Trusted_Connection=yes;database=northwind");

! Using OleDbConnection
OleDbConnection
OleDbConnection myOleDbConnection
myOleDbConnection == new
new
OleDbConnection("server=(local)\\NetSDK;
OleDbConnection("server=(local)\\NetSDK; !
!
Trusted_Connection=yes;database=northwind;
Trusted_Connection=yes;database=northwind; !
!
provider=sqloledb");
provider=sqloledb");

*ILLEGAL FOR NON-TRAINER USE**

When you connect to a database, there are two routes that you can take: use
OLE DB or use the native SQL provider. The native SQL provider is faster, but
you must use Microsoft SQL Server as your database. If you are using
Microsoft Access, Microsoft Excel, a comma-delimited file, or some other data
source, you must use the OLE DB provider. You can use the OLE DB provider
with a Microsoft SQL Server database; however, it is not as fast as using the
native SQL provider.
The Connection object defines how to connect to a specific data store. The
.NET Framework provides two Connection objects: SqlConnection and
OleDbConnection. The SqlConnection object defines how to connect to
SQL Server databases and the OleDbConnection object allows you to establish
a connection to a database through an OLE DB provider.

Using SqlConnection
The following code illustrates how to create and open a connection to a
Delivery Tip Microsoft SQL Server database by using the SqlConnection object.
Point out to students that in
ADO.NET you do not SqlConnection mySqlConnection = new
always need to explicitly SqlConnection("server=(local)\\NetSDK;!
open and close the
Trusted_Connection=yes;database=northwind");
connection to the database.

Warning Embedded usernames/passwords in database connection strings are

inherently unsecure, and should only be used on platforms, such as Microsoft
Windows® 9x, that do not support Integrated Security.
For more information about Integrated Security, see the .NET Framework SDK
documentation.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 11

Using OleDbConnection
For the OLE DB Managed Provider, the connection string format is quite
similar to the connection string format used in OLE DB.
The following code illustrates how to create and open a connection to a
Microsoft SQL Server database by using OleDbConnection.
OleDbConnection myOleDbConnection = new
OleDbConnection("server=(local)\\NetSDK;!
Trusted_Connection=yes;database=northwind;!
provider=sqloledb");

The examples in this module, use SqlConnection objects. Implementation is

Delivery Tip slightly different for using OleDbConnection objects. For more information
Stress to students that all
examples in the module and
about using OleDbConnection objects, search for OleDbConnection in the
lab will use SqlConnection Microsoft .NET Framework SDK documentation.
objects.
Choosing a .NET Data Provider
Depending on the design and data source for your application, your choice of
.NET data provider can improve the performance, capability, and integrity of
your application. The following table discusses the advantages and limitations
of each .NET data provider.
Provider Notes

SQL Server Recommended for middle-tier applications that use Microsoft

.NET Data Provider SQL Server 7.0 or later.
Recommended for single-tier applications that use Microsoft
Data Engine (MSDE) or Microsoft SQL Server 7.0 or later.
Recommended over use of the OLE DB Provider for
SQL Server (SQLOLEDB) with the OLE DB .NET Data
Provider.
For Microsoft SQL Server version 6.5 and earlier, you must
use the OLE DB Provider for SQL Server with the OLE DB
.NET Data Provider.
OLE DB .NET Recommended for middle-tier applications that use Microsoft
Data Provider SQL Server 6.5 or earlier, or any OLE DB provider that
supports the OLE DB interfaces listed in OLE DB Interfaces
Used by the OLE DB .NET Data Provider (OLE DB 2.5
interfaces are not required).
For Microsoft SQL Server 7.0 or later, the SQL Server .NET
Data Provider is recommended.
Recommended for single-tier applications that use Microsoft
Access databases. Use of a Microsoft Access database for a
middle-tier application is not recommended.
Support for the OLE DB Provider for ODBC (MSDASQL) is
disabled. For access to Open Database Connectivity (ODBC)
data sources, an ODBC .NET Data Provider is available as a
separate download at http://msdn.microsoft.com/downloads.
12 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

" Accessing Data with DataSets

Topic Objective
To introduce the topics
included in the section.
! Using DataSets to Read Data
Lead-in
After connecting to a ! Storing Multiple Tables in a DataSet
database, the next step is to
access data from it. ! Using DataViews
! Updating a Database from a DataSet
! Displaying Data in the DataGrid Control

*ILLEGAL FOR NON-TRAINER USE**

ADO.NET provides two ways to access data, DataSets and DataReaders.
In this section, you will learn how to access data by using DataSets. You will
also learn about DataViews and displaying data in DataGrid controls.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 13

Using DataSets to Read Data

Topic Objective
To describe how to retrieve
data from a database by
using DataSets. ! Create the Database Connection
Lead-in ! Store the Query in a SqlDataAdapter
Now that we can establish a
connection, we need to be SqlDataAdapter
SqlDataAdapter mySqlDataAdapter
mySqlDataAdapter ==
able to execute statements new
new SqlDataAdapter(
SqlDataAdapter(
against the database to "select
"select ** from
from customers",
customers", mySqlConnection);
mySqlConnection);
retrieve data.
! Create and Populate the DataSet with DataTables
DataSet
DataSet myDataSet
myDataSet == new
new DataSet();
DataSet();
mySqlDataAdapter.Fill(myDataSet,"Customers");
mySqlDataAdapter.Fill(myDataSet,"Customers");

*ILLEGAL FOR NON-TRAINER USE**

After you establish a connection to a database, you can access its data.
Delivery Tip
Explain the parameters to ADO.NET provides multiple ways to access data.
the Fill method. The second
parameter is the name that
will be given to the Using DataSets
DataTable created in the The DataSet object is the centerpiece of ADO.NET. It represents a complete
DataSet. You use this name set of data, including multiple, related tables, and constraints.
when reading data from the
DataSet. Although a DataSet stores data, you need DataAdapter objects to create and
initialize the various tables. You also need the Fill method to populate a
DataSet with the results from a query.
The Fill method takes two parameters: a DataSet instance and a string. The
DataSet instance represents the DataSet to be filled, and the string identifies
the DataTable that will be created inside the DataSet. A DataSet can contain
many DataTables. You use the string supplied to the Fill method to reference
the DataTable after it is created.
14 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

The following code example illustrates how to create a SqlDataAdapter object

that contains the query statement. The Fill method then populates the DataSet
with the results from the query.
// Create a connection
SqlConnection mySqlConnection = new
SqlConnection("server=(local)\\NetSDK;!
Trusted_Connection=yes;database=northwind");
// Create the DataAdapter
SqlDataAdapter mySqlDataAdapter = new SqlDataAdapter(
"select * from customers", mySqlConnection);
// Create and populate the DataSet
DataSet myDataSet = new DataSet();
mySqlDataAdapter.Fill(myDataSet,"Customers");

Displaying Data In A DataSet

Because the data is stored in a collection of rows in the table, you can easily use
a foreach statement to iterate through the rows:
foreach (DataRow myDataRow in
myDataSet.Tables["Customers"].Rows)
{
Console.WriteLine(
" CustomerID: {0}",
myDataRow["CustomerID"].ToString);
}

Typed DataSet
Along with late bound access to values through weakly typed variables, the
DataSet provides access to data through a strongly typed metaphor. By using
user-friendly names and strongly typed variables, you can access tables and
columns that are part of the DataSet. You can also transport a strongly typed
DataSet by using an XML Web service.
A typed DataSet is a class that derives from a DataSet. As such, it inherits all
of the methods, events, and properties of a DataSet. Additionally, a typed
DataSet provides strongly typed methods, events, and properties. This means
that you can access tables and columns by name, instead of using collection-
based methods. Aside from the improved readability of the code, a typed
DataSet also allows the Microsoft Visual Studio® .NET code editor to
automatically complete lines as you type.
Additionally, a strongly typed DataSet provides access to the correct types for
values at compile time. With a strongly typed DataSet, type mismatch errors
are caught when the code is compiled rather than at run time.
Using an XML Schema that complies with the XML Schema definition
language (XSD) standard, you can generate a strongly typed DataSet by using
the XSD.exe tool that is provided with the .NET Framework SDK. The use of
this tool is outside the scope of this module.
You will see how to easily create and use a typed DataSet using Visual Studio
.NET in this module’s lab.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 15

Storing Multiple Tables in a DataSet

Topic Objective ! Add the First Table
To explain how to retrieve SqlDataAdapter
and store multiple tables in SqlDataAdapter mySqlDataAdapter
mySqlDataAdapter == new
new SqlDataAdapter(
SqlDataAdapter(
"select
"select ** from
from customers",mySqlConnection);
customers",mySqlConnection);
a DataSet. DataSet
DataSet myDataSet
myDataSet == new
new DataSet();
DataSet();
Lead-in mySqlDataAdapter.Fill(myDataSet,"Customers");
mySqlDataAdapter.Fill(myDataSet,"Customers");
Unlike a disconnected ! Add the Subsequent Table(s)
recordset, a DataSet can
hold more than one table. mySqlDataAdapter.SelectCommand.CommandText
mySqlDataAdapter.SelectCommand.CommandText ==
"select
"select ** from
from orders";
orders";
mySqlDataAdapter.Fill(myDataSet,"Orders");
mySqlDataAdapter.Fill(myDataSet,"Orders");

DataSet: Customers
Orders

Data Tables

*ILLEGAL FOR NON-TRAINER USE**

A DataSet can contain multiple tables. You can retrieve multiple tables from a
database and store them in a DataSet.

Note You can store tables from different databases in the same DataSet.

Delivery Tip ! To retrieve and store multiple tables in a DataSet

Tell students that they can 1. Create and populate the first DataSet.
create new relationships
between the tables in a DataSet myDataSet = new DataSet();
DataSet. string strSql ="select * from customers";
SqlDataAdapter mySqlDataAdapter = new SqlDataAdapter(
strSql, mySqlConnection);
mySqlDataAdapter.Fill(myDataSet,"Customers");

2. Reset the SelectCommand, InsertCommand, or DeleteCommand

property of the DataAdapter object to a new command string.
strSql = "select * from orders";
mySqlDataAdapter.SelectCommand.CommandText = strSql;

3. Call Fill again.

mySqlDataAdapter.Fill(myDataSet,"Orders");
16 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

The following code shows how you can add two tables from two different
queries, one for authors and the other for titles, to the same DataSet.
// create connection to database
string strConn =
"server=(local)\\NetSDK;!
Trusted_Connection=yes;database=northwind";
SqlConnection mySqlConnection = new SqlConnection(strConn);

string strSql = "select * from customers"

SqlDataAdapter mySqlDataAdapter =
new SqlDataAdapter(strSql, mySqlConnection);
//fill DataSet with first set of data
DataSet myDataSet = new DataSet();
mySqlDataAdapter.Fill(myDataSet,"Customers");
//fill DataSet with first set of data
strSql = "select * from orders"
mySqlDataAdapter.SelectCommand.CommandText = strSql;
mySqlDataAdapter.Fill(myDataSet,"Orders");
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 17

Using DataViews
Topic Objective
To explain the role of
DataViews in accessing
data from a database by ! DataViews Can be Customized to Present a Subset of
using DataSets. Data from a DataTable
Lead-in ! The DefaultView Property Returns the Default DataView
To display data in a for the Table
DataSet, you can use a
DataView. DataView
DataView myDataView
myDataView ==
myDataSet.Tables["Customers"].DefaultView;
myDataSet.Tables["Customers"].DefaultView;

! Setting Up Different Views

myDataView.Sort
myDataView.Sort == "Country";
"Country";
myDataView.RowFilter
myDataView.RowFilter == "Country
"Country == 'Argentina'";
'Argentina'";

*ILLEGAL FOR NON-TRAINER USE**

There are many ways to filter data. One way is to filter data at the database
command level, by using a where clause in your query. A second way is to
filter the data after it is in the DataSet. This topic covers filtering in the
DataSet.

Filtering and Sorting with DataViews

To display the data held in a DataSet, you can use a DataView.
DataViews can be customized to present a subset of data from the DataTable.
This capability allows you to have two controls bound to the same DataTable,
but showing different versions of the data. For example, one control may be
bound to a DataView that shows all the rows in the table, and a second may be
configured to display only the rows that have been deleted from the DataTable.
Each DataTable in a DataSet has a DefaultView property, which returns the
default view for the table. You can access the default DataView of a DataSet
as follows:
DataView myDataView =
myDataSet.Tables["Customers"].DefaultView;

Note The DataSet object contains a Tables collection. You reference the
DataTable you are interested in by name.

You can sort the data. For example, you can sort the customers by country.
myDataView.Sort = "Country";
18 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

Setting up a Different View of a DataSet

You can also create a view of a subset of the data in a DataTable. For example,
you can set the RowFilter property on a DataView to retrieve only customers
from Argentina.
myDataView.RowFilter = "Country = 'Argentina'";

For more information about the properties of the DataView object, see the
Microsoft .NET Framework SDK documentation.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 19

Updating a Database From a DataSet

Topic Objective ! SQLCommandBuilder generates Update command
To show how to update data SqlCommandBuilder
SqlCommandBuilder mySqlCommandBuilder
mySqlCommandBuilder == new
new
in a Database from a SqlCommandBuilder(mySqlDataAdapter);
SqlCommandBuilder(mySqlDataAdapter);
DataSet.
! Set the MissingSchemaAction property
Lead-in mySqlDataAdapter.MissingSchemaAction
This topic illustrates how to mySqlDataAdapter.MissingSchemaAction ==
MissingSchemaAction.AddWithKey;
MissingSchemaAction.AddWithKey;
update data in a database
using a DataSet. You can ! Add a row
also insert, update, and
delete data in a database DataRow
DataRow myDataRow
myDataRow ==
directly using a myDataSet.Tables["Customers"].NewRow();
myDataSet.Tables["Customers"].NewRow();
SqlCommand as described myDataRow["CustomerId"]
myDataRow["CustomerId"] == "NewID";
"NewID";
in the .NET Framework //
// ...
...
SDK. myDataSet.Tables["Customers"].Rows.Add(myDataRow);
myDataSet.Tables["Customers"].Rows.Add(myDataRow);
! To submit the data
mySqlDataAdapter.Update(myDataSet,
mySqlDataAdapter.Update(myDataSet, "Customers");
"Customers");
*****************************ILLEGAL FOR NON-TRAINER USE******************************
This topic illustrates how to update data in a database by using a DataSet. You
can also insert, update, and delete data in a database directly by using a
SqlCommand as described in the .NET Framework SDK documentation.
After a DataSet is loaded, you can modify the data, and the DataSet will track
the changes. The DataSet may be considered an in-memory cache of data that
is retrieved from a database. In this topic, you will see how to use the Add
method on the DataTable to add new data to a DataSet. The Add method takes
either an array of the expected data columns, or a DataRow.
To load the DataSet from the database:
SqlConnection myConnection = new SqlConnection(
"server=(local)\\NetSDK;!
Trusted_Connection=yes;database=northwind");
SqlDataAdapter mySqlDataAdapter = new SqlDataAdapter(
"Select * from Customers",
myConnection);
DataSet myDataSet = new DataSet();

Before you can submit the update back to the database, you must set up the
InsertCommand, UpdateCommand, and DeleteCommand to reconcile the
changes to the database. For limited scenarios you can use the
SqlCommandBuilder to automatically generate those for you:
SqlCommandBuilder mySqlCommandBuilder = new
SqlCommandBuilder(mySqlDataAdapter);
20 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

Because Fill will not cause primary key and unique key information to be
retrieved unless AddWithKey is specified, you must set the
MissingSchemaAction property to AddWithKey:
mySqlDataAdapter.MissingSchemaAction =
MissingSchemaAction.AddWithKey;

mySqlDataAdapter.Fill(myDataSet, "Customers");

DataRow myDataRow;
myDataRow = myDataSet.Tables["Customers"].NewRow();

The DataTable must return a DataRow through the NewRow method. The
method returns a DataRow object with the appropriate schema of the
DataTable. The new DataRow is independent of the table until it is added to
the RowsCollection.

myDataRow["CustomerId"] = "NewID";
myDataRow["ContactName"] = "New Name";
myDataRow["CompanyName"] = "New Company Name";

myDataSet.Tables["Customers"].Rows.Add(myDataRow);

To submit the data from the DataSet into the database, use the Update method
on the SqlDataAdapter.
mySqlDataAdapter.Update(myDataSet, "Customers");

You can change data in a DataRow by accessing the DataRow. You can use
the index of the row in the RowsCollection that is accessed through the Rows
property:
myDataSet.Tables["Customers"].Rows[0]["ContactName"]="Peach";

You can also access a specific row by the primary key value:
DataRow myDataRow1 =
myDataSet.Tables["Customers"].Rows.Find("ALFKI");
myDataRow1["ContactName"]="Peach";

In the preceding example, "ALFKI" is the value of the primary key

"CustomerID" in the Customers table. When using the SqlDataAdapter, the
key is established from the database. You can also set the key through the
PrimaryKey property if you are not using the database.
Use the Delete method to remove the Row. Note that a logical deletion occurs
in the DataSet, which only results in a hard deletion after the DataSet is
updated to the database. Similarly, you can use RejectChanges on the DataSet,
in which case the Row is restored.
myDataSet.Tables["Customers"].Rows[0].Delete();

The original and new values are maintained in the row. The RowChanging
event allows you to access both original and new values to decide whether you
want the edit to proceed. Because original and new values are maintained, you
can establish scenarios such as optimistic locking and key changes.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 21

Demonstration: Accessing Data with DataSets

Topic Objective
To demonstrate how to
open a database, create a
DataSet with multiple tables,
and create views on the
data.
Lead-in
In this demonstration, you
will see how to access data
with a DataSet.

*ILLEGAL FOR NON-TRAINER USE**

In this demonstration, you will see how to access data with a DataSet.
Run the Visual Studio .NET Accessing Data with DataSets project from the
following location:
<install folder>\Democode\Mod16\Demo16.1
The code reads in data from database tables, creates views, and updates the
database.

Tip You can examine the database tables and stored procedures by using the
Server Explorer window Data Connections entries.
22 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

Running this program produces output that is similar to the following:

Opened Connection to!
server=(local)\NetSDK;!
Trusted_Connection=yes;database=northwind
Total Number of Regions: 4
Total Number of Customers: 91

Regions:
ID: 1 Description: Eastern
ID: 2 Description: Western
ID: 3 Description: Northern
ID: 4 Description: Southern

First 5 Customer IDs:

Customer ID: ALFKI
Customer ID: ANATR
Customer ID: ANTON
Customer ID: AROUT
Customer ID: BERGS

View sorted by country

First 5 Customers in the view:
Customer ID: CACTU Country: Argentina
Customer ID: OCEAN Country: Argentina
Customer ID: RANCH Country: Argentina
Customer ID: ERNSH Country: Austria
Customer ID: PICCO Country: Austria

Filtered by country equals Argentina

Customers with Country = Argentina, number of entries 3
ID: CACTU Country: Argentina
ID: OCEAN Country: Argentina
ID: RANCH Country: Argentina
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 23

Displaying Data in the DataGrid Control

Topic Objective
To describe how to display
data on the client DataGrid ! Create a Windows Forms DataGrid control
controls.
dataGrid1
dataGrid1 == new
new System.Windows.Forms.DataGrid();
System.Windows.Forms.DataGrid();
Lead-in
After you connect to a data
source and retrieve data ! Bind to a DataSet
from it, the next step is to
display the data on the dataGrid1.DataSource
dataGrid1.DataSource == myDataSet;
myDataSet;
client. dataGrid1.DataMember
dataGrid1.DataMember == "Regions";
"Regions";
! Using a custom view

DataView
DataView myDataView
myDataView ==
myDataSet.Tables["Customers"].DefaultView;
myDataSet.Tables["Customers"].DefaultView;
myDataView.RowFilter
myDataView.RowFilter == "Country
"Country == 'Argentina'";
'Argentina'";
dataGrid2.DataSource
dataGrid2.DataSource == myDataView;
myDataView;

*ILLEGAL FOR NON-TRAINER USE**

Displaying data from a data source is extremely simple and flexible in either
Windows Forms or ASP.NET. These application development environments
include a set of controls that perform the function of displaying data. You only
need to bind these controls to a data source.
To display data on the client, you can use any list-bound control, such as the
DataGrid.

Using the DataGrid Control

The DataGrid control is designed to produce output that resembles a
worksheet. In Visual Studio .NET, you can drag and drop a DataGrid from the
Toolbox onto the Design window. This generates code to create a DataGrid
object as follows:
dataGrid1 = new System.Windows.Forms.DataGrid();

To bind a DataSet to a DataGrid control, you first set the DataSource

property of the DataGrid to a DataTable, or DataVieweither the
DefaultView property of a DataSet or a custom DataView object.
To specify a DataTable, set the DataMember property of the DataGrid to the
name of the DataTable.
24 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

Example Binding to a DataSet

dataGrid1.DataSource = myDataSet;
dataGrid1.DataMember = "Regions";

Alternatively, you can use the Tables collection of the DataSet to assign the
DataTable directly to the DataSource of the DataGrid, as in the following
example:
dataGrid1.DataSource = myDataSet.Tables["Regions"];

If you want to display a different view of data in the DataGrid control, create a
new DataView object from the DataSet and bind that to the control. For
example, the following code will display only those customers in Argentina.

Example Using a Custom View

DataView myDataView =
myDataSet.Tables["Customers"].DefaultView;
myDataView.RowFilter = "Country = 'Argentina'";
dataGrid2.DataSource = myDataView;
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 25

Demonstration: Displaying Data in a DataGrid

Topic Objective
To introduce the Data Grid.
Lead-in
In this demonstration, you
will see how to create a
Windows Form that reads
data from a database and
displays it in a DataGrid
control.

*ILLEGAL FOR NON-TRAINER USE**

In this demonstration, you will see how to read data from a database into a
DataSet and then display it in a DataGrid control.
Run the Visual Studio .NET DataGrid project from the following location:
<install folder>\Democode\Mod16\Demo16.2
Running this program displays a button labeled “Load Data” and two DataGrid
controls. Clicking the button reads region and customer data from a database
and displays them in the grids. A DataView object is used to display only those
customers in Argentina.
26 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

" Using Stored Procedures

Topic Objective
To introduce the topics in
this section.
! Calling Stored Procedures
Lead-in
When working with data ! Passing Parameters
from a data source, the
ability to use stored ! Calling Action Stored Procedures
procedures is important.

*ILLEGAL FOR NON-TRAINER USE**

In the past, data processing has been primarily connection-based. Now, in an
effort to make multi-tiered applications more efficient, data processing is
turning to a message-based approach that revolves around chunks of
information. In ADO.NET, this is accomplished by the DataAdapter object,
which provides a bridge to retrieve and save data between a DataSet object and
its source data store. The DataAdapter object accomplishes this by invoking
the appropriate SQL commands against the data store.
Both the SqlDataAdapter and the OleDbDataAdapter classes feature four
command objects, InsertCommand, UpdateCommand, DeleteCommand,
and SelectCommand. These objects provide the create, update, delete, and
read functions for a specific DataTable in the DataSet.
These command objects are used when you want to perform a number of
updates at the same time. Instead of having one stored procedure to do it all,
you can put SQL Statements in each object and call the Update method.
For more information about these command objects, see the .NET Framework
SDK documentation.
However, the easier and more commonly used method of updating data in a
database is to use stored procedures. You can use stored procedures to read and
modify data from a database. You can call stored procedures both from
DataAdapter and Command objects.
In this section, you will learn how to call stored procedures, pass parameterized
stored procedures, and call action stored procedures.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 27

Calling Stored Procedures

Topic Objective
To explain how to use ! Stored Procedures Provide Security for Database
stored procedures to
retrieve data in a database. ! Set Up the DataAdapter
Lead-in SqlDataAdapter
SqlDataAdapter mySqlDataAdapter
mySqlDataAdapter == new
new
Like ADO, ADO.NET allows SqlDataAdapter();
SqlDataAdapter();
developers to use stored mySqlDataAdapter.SelectCommand
mySqlDataAdapter.SelectCommand == new
new SqlCommand();
SqlCommand();
procedures to modify data. mySqlDataAdapter.SelectCommand.Connection
mySqlDataAdapter.SelectCommand.Connection ==
mySqlConnection;
mySqlConnection;
mySqlDataAdapter.SelectCommand.CommandText
mySqlDataAdapter.SelectCommand.CommandText ==
"GetProducts";
"GetProducts";
mySqlDataAdapter.SelectCommand.CommandType
mySqlDataAdapter.SelectCommand.CommandType ==
CommandType.StoredProcedure;
CommandType.StoredProcedure;
! Run the Stored Procedure and Store Returned Records
mySqlDataAdapter.Fill(myDataSet,"Products");
mySqlDataAdapter.Fill(myDataSet,"Products");

*ILLEGAL FOR NON-TRAINER USE**

A stored procedure is a sequence of Transact-SQL (T-SQL) statements stored
on the database server. Stored procedures provide a level of security to a
database. The database designer can create stored procedures to retrieve and
modify data, and not allow developers access to the actual tables of the
database. In this way, the database designer can then change the structure of the
database without breaking applications that use it.
Though it is not always the case, stored procedures can return a set of records.
Stored procedures can encapsulate repetitive tasks and execute them efficiently.
When you call a stored procedure that returns a set of records, use a
DataAdapter and the Fill method. When you call a stored procedure that
performs some function on the database but does not return a set of records, use
a Command object and the ExecuteNonQuery method.
28 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

Calling a Select Stored Procedure

Using stored procedures in ADO.NET is similar to ADO. You create a
Command object and point it to the database connection. Next, you set the
CommandText property to the name of the stored procedure and the
CommandType property to CommandType.StoredProcedure.
The following is the GetProducts stored procedure. It returns a list of
ProductNames.
PROCEDURE GetProducts as select ProductName from Products

Using a Connection object named mySqlConnection, the following example

shows how to setup the SqlDataAdpator for the GetProducts stored
procedure:
SqlDataAdapter mySqlDataAdapter = new
SqlDataAdapter();
mySqlDataAdapter.SelectCommand = new SqlCommand();
mySqlDataAdapter.SelectCommand.Connection = mySqlConnection;
mySqlDataAdapter.SelectCommand.CommandText = "GetProducts";
mySqlDataAdapter.SelectCommand.CommandType =
CommandType.StoredProcedure;

Note You can directly set the connection and command text when creating the
SqlDataAdapter object:
SqlDataAdapter mySqlDataAdapter = new
SqlDataAdapter(
"GetProducts", mySqlConnection);

You then set the CommandType property before you call the Fill method.
mySqlDataAdapter.SelectCommand.CommandType =
CommandType.StoredProcedure;

To execute the stored procedure, call the Fill method of the

mySqlDataAdapter object. This fills a DataTable object with the returned
records of the stored procedure.
DataSet myDataSet = new DataSet();
mySqlDataAdapter.Fill(myDataSet,"Products");

After you have filled a DataTable with the results of a Select stored procedure,
you can bind it to a list-bound control to display the data. For example, to bind
to a Windows Forms DataGrid control named dataGrid1:
dataGrid1.DataSource =
myDataSet.Tables["Products"];
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 29

Passing Parameters
Topic Objective
To show students how to ! Create Parameter, Set Direction and Value, Add to the
use parameterized stored Parameters Collection
procedures.
SqlParameter
SqlParameter workParam
workParam == new
new
Lead-in SqlParameter("@ProductName",SqlDbType.NChar,
When using Microsoft SqlParameter("@ProductName",SqlDbType.NChar, 40);
40);
SQL Server, or other
workParam.Direction
workParam.Direction ==
procedure-based
databases, you can use ParameterDirection.Input;
ParameterDirection.Input; //
// Input
Input is
is default
default
parameters to pass and workParam.Value = textBox1.Text;
workParam.Value = textBox1.Text;
retrieve information from the
database. mySqlDataAdapter.SelectCommand.Parameters.Add(
mySqlDataAdapter.SelectCommand.Parameters.Add(
workParam);
workParam);

! Run Stored Procedure

DataSet
DataSet myDataSet
myDataSet == new
new DataSet();
DataSet();
mySqlDataAdapter.Fill(myDataSet,"ProductData");
mySqlDataAdapter.Fill(myDataSet,"ProductData");
*****************************ILLEGAL FOR NON-TRAINER USE******************************
When using Microsoft SQL Server, or other procedure-based databases,
Delivery Tip parameters can be used to pass and retrieve information from the database.
Stress that, when you create
a parameter, you must use
Using parameters in ADO.NET works just as it does in ADO. You can pass the
the same name that was string in the command or use the parameters collection.
used in the stored
When using parameters, the names of the parameters added to the parameters
procedure. Also, stress that
the order in which you
collection of the command must match the names of the parameter markers in
create parameters does not the stored procedure.
matter.
Parameters
Your application can pass specific data to a stored procedure by using
parameters. The following table describes the types of parameters that are
available to you.
Direction Use

Input Used by your application to send specific data values to a stored

procedure.
Output Used by a stored procedure to send specific values back to the calling
application.
InputOutput Used by a stored procedure to both retrieve information sent by your
application and to send specific values back to the application.
ReturnValue Used by a stored procedure to send a return value back to the calling
application.
30 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

Creating a Parameter
To create a parameter for the SqlDataAdapter object, create a new
SqlParameter object with the name and data type of the parameter. Next, set
the Direction property of the new parameter to indicate how the parameter is
used by the stored procedure. If the parameter is an input parameter, set the
Value property to specify the data that should be sent to the server.
For example, the GetProductData stored procedure takes one input parameter:
PROCEDURE GetProductData !
@ProductName nchar(40) as select * from Products !
where @ProductName = ProductName

To call the GetProductData stored procedure, create an input parameter named

@ProductName and set its value to the Text property of a text box named
textBox1.
SqlDataAdapter mySqlDataAdapter = new
SqlDataAdapter();
mySqlDataAdapter.SelectCommand = new SqlCommand();
mySqlDataAdapter.SelectCommand.Connection = mySqlConnection;
mySqlDataAdapter.SelectCommand.CommandText = "GetProductData";
mySqlDataAdapter.SelectCommand.CommandType =
CommandType.StoredProcedure;

SqlParameter workParam = new SqlParameter("@ProductName",

SqlDbType.NChar, 40);
// ParameterDirection.Input is the default for the Direction
// property. Thus the following line is not needed here.
// To set the Direction property to its default value,
// use the following line.
// workParam.Direction = ParameterDirection.Input;
workParam.Value = textBox1.Text;

After you have created the parameter, use the Add method of the Parameters
collection of the SelectCommand object. The Add method takes a
SqlParameter as an argument. If a stored procedure has more than one
parameter, it does not matter in which order you add them because you create
them by name.
mySqlDataAdapter.SelectCommand.Parameters.Add(workParam);

Use the Fill method to run the stored procedure and retrieve the records.
DataSet myDataSet = new DataSet();
mySqlDataAdapter.Fill(myDataSet,"ProductData");
// bind to a DataGrid
dataGrid.DataSource = myDataSet.Tables["ProductData"];
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 31

Calling Action Stored Procedures

Topic Objective
To show how to call a stored
! Use SQLCommand object
procedure that does not SqlCommand
SqlCommand mySqlCommand
mySqlCommand == new
new
return records. SqlCommand("GetProductCount",
SqlCommand("GetProductCount", mySqlConnection);
mySqlConnection);
mySqlCommand.CommandType
mySqlCommand.CommandType ==
Lead-in
CommandType.StoredProcedure;
CommandType.StoredProcedure;
When calling a stored
SqlParameter
SqlParameter workParam
workParam == new
new
procedure that does not SqlParameter("@ProductCount",
return records, you use the SqlParameter("@ProductCount", SqlDbType.Int);
SqlDbType.Int);
workParam.Direction
workParam.Direction == ParameterDirection.Output;
ParameterDirection.Output;
SqlCommand directly and mySqlCommand.Parameters.Add(workParam);
mySqlCommand.Parameters.Add(workParam);
call the ExecuteNonQuery
method to run it. ! Call the ExecuteNonQuery Method
mySqlCommand.ExecuteNonQuery();
mySqlCommand.ExecuteNonQuery();
! Retrieve Output Parameters
textBox2.Text
textBox2.Text ==
mySqlCommand.Parameters["@ProductCount"].!
mySqlCommand.Parameters["@ProductCount"].!
Value.ToString();
Value.ToString();
*****************************ILLEGAL FOR NON-TRAINER USE******************************
When calling a stored procedure that does not return records, you use the
SqlCommand directly and call the ExecuteNonQuery method to run it.
The GetProductCount stored procedure returns the number of products:
PROCEDURE GetProductCount @ProductCount int out as !
select @ProductCount=COUNT(ProductID) from Products

Because this stored procedure does not return a set of records, you do not need
to use a DataAdapter object. Instead, you can use a Command object directly,
and call the ExecuteNonQuery method to run the stored procedure.
To call this stored procedure, create an output parameter named
@ProductCount, add it to the Parameters collection of a Command object,
and then call ExecuteNonQuery to run the stored procedure:
SqlCommand mySqlCommand = new
SqlCommand("GetProductCount", mySqlConnection);
mySqlCommand.CommandType = CommandType.StoredProcedure;

SqlParameter workParam = new

SqlParameter("@ProductCount", SqlDbType.Int);
workParam.Direction = ParameterDirection.Output;
mySqlCommand.Parameters.Add(workParam);

// execute the stored procedure

mySqlCommand.ExecuteNonQuery();
32 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

Retrieving an Output Parameter

If you need to retrieve a value from a stored procedure that returns a value or
Delivery Tip sets an output parameter, use the Parameters collection to find the value of the
If a stored procedure returns
records and an output
output parameter. You can reference the value of the output parameter by name
parameter, retrieve the or index.
records in the usual way by
The following example code retrieves the value of the @ProductCount output
calling the Fill method.
parameter by name and assigns it to a text box named textBox2:
textBox2.Text =
mySqlCommand.Parameters["@ProductCount"].Value.ToString();
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 33

Demonstration: Calling Stored Procedures

Topic Objective
To introduce the
demonstration.
Lead-in
In this demonstration, you
will see how to call stored
procedures both with and
without parameters.

*ILLEGAL FOR NON-TRAINER USE**

In this demonstration, you will see how to create and call stored procedures
with and without parameters.
Run the Visual Studio .NET StoredProcedure project from the following
location:
<install folder>\Democode\Mod16\Demo16.3

Tip You can examine the database tables and stored procedures by using the
Server Explorer window Data Connections entries.

To create and execute a stored procedure that returns the product names of all
the entries in the Products table, click the Load Product Names button.
Typing a name in the text box that is labeled Enter Product Name allows you
to click on the Load Product Data button. This button creates and executes a
stored procedure that takes the product name as an input parameter and returns
all the fields of that product.
To create and execute a stored procedure that has an output parameter, which
gets set to the number of products in the database’s Products table, click the
Get Number of Products button.
34 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

Lab 16: Using ADO.NET to Access Data

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will create an
XML Web service and a
Windows form that reads
and updates database
records by using ADO.NET.

*ILLEGAL FOR NON-TRAINER USE**

Explain the lab objectives.
Objectives
After completing this lab, you will be able to:
! Use the rapid application design facilities of Visual Studio .NET to create an
XML Web service whose methods can be used to read and update a
database by using ADO.NET.
! Use Visual Studio .NET rapid application design facilitates to create a
Windows Forms application that displays and enables a user to update a
DataGrid control that is bound to a DataSet. The DataSet is obtained and
updated by using an XML Web service.

Lab Setup
Only solution files are associated with this lab. The solution files for this lab are
in the folder <installfolder>\Labs\Lab16\Solution.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 35

Scenario
This lab is based on the Visual Studio .NET Framework SDK Walkthrough:
Creating a Distributed Application. In this lab, you will create a multi-tiered,
distributed application.
The application consists of three logical tiers: data, business object, and user
interface. The data tier is a SQL Server database. The business object tier
handles the tasks of accessing the data and distributing it to the clients. The user
interface tier consists of a Windows-based application.
You will create the Authors XML Web service and the Windows Client
Application. The following diagram shows the architecture of the distributed
application:

As part of the distributed application, you will build a simple data application
with look-up and update functionality. You will create an XML Web service to
retrieve data from the Authors table in the SQL Server Pubs sample database.
You will also build a Windows-based client application to display the results of
the query by the XML Web service. The communication between the client and
the XML Web service is handled by using HTTP and XML.
For this lab, the data has already been generated and is available in the Pubs
sample database. Therefore, you will begin by creating the business object, the
XML Web service, followed by building the Windows Form user interface.

Estimated time to complete this lab: 60 minutes

36 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

Exercise 1
Creating the Middle-Tier Business Object
In this exercise, you will create a business object that runs on a Web server.
You will implement the business object as an XML Web service that holds the
data connections and dataset definition.
After first creating an ASP.NET Web Service project in Visual Studio .NET,
you will use the Visual Studio .NET design environment to add a data
connection, a data adapter, and a dataset class definition to the XML Web
service. You will add two methods to the XML Web service: GetAuthors,
which returns a dataset from the database, and UpdateAuthors, which updates
the database with changes from the user.

! Create a ASP.NET Web Service project

1. Open Visual Studio .Net and on the File menu, click New, and then click
Project to display the New Project dialog box.
2. In the Project Types pane, click Visual C# Projects, and then select
ASP.NET Web Service in the Templates pane.
3. In the Location box, type the name of the Web server,
http://localhost/AuthorsWebService. The dimmed Name box will now
contain the text: AuthorsWebService. Click OK.
4. The AuthorsWebService project is added to the solution. The Component
Designer for Service1.asmx appears in the development environment. In this
component, you will create a connection to the data store and obtain an
instance of the data by using a dataset. In Solution Explorer, double-click
Service1.asmx.
5. In the Properties window, set the Name property of Service1 to
AuthorsService.
6. In Solution Explorer, right-click the Service1.asmx file, click Rename,
and rename the file AuthorsService.asmx, to match the service name.

! Create a database connection and data adapter

1. If Server Explorer is not visible, on the View menu, click Server
Explorer.
2. In Server Explorer, right-click the Data Connections node and on the
shortcut menu, click Add Connection.
3. In the Connection tab of the Data Link Properties dialog box, type the
name of the SQL Server where the pubs database is installed:
(local)\NETSDK
Select Use Windows NT Integrated security for the logon information.
4. Select the pubs database from the list. Click Test Connection to validate
the information that you provided, and then click OK to establish the
connection.
A new node appears in the Data Connections node of Server Explorer.
5. In Server Explorer, expand the node for the new connection node and then
expand the Tables node.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 37

6. Find the authors node and expand it to show the fields in the authors table.
7. Using CTRL+Click, select the au_id, au_lname, au_fname, and city fields.
8. Drag these fields from Server Explorer onto the design surface.
A SqlConnection that is paired with a SqlDataAdapter appears in the
designer. A connection has now been created to the database, with the
transfer of information to be handled by the SqlDataAdapter. These
components are configured to move a dataset with the selected fields of the
authors table in and out of the database.

! Configure Integrated Windows authentication

1. Start the Internet Information Services tool. It can be run from the Start
button, Control Panel, Performance and Maintenance, Administrative
Tools.
2. Expand the node for your server.
3. Expand the Default Web Site node.
4. Right-click the node for AuthorsWebService and click Properties.
5. Click the Directory Security tab.
6. Click the Edit button in the Anonymous access and authentication
control section, click the Edit button.
7. Clear the Anonymous access check box.
8. Select the Integrated Windows authentication check box. Click OK to
return to the AuthorsWebService Properties and click OK again. You
have now configured your XML Web service directory.
9. Returning to the project in Visual Studio, in Solution Explorer, double-
click the Web.config file.
10. Add the following tag on the line after the <system.web> tag to configure
integrated security for your XML Web service.
<identity impersonate="true"/>

! Create a dataset class definition

1. In Solution Explorer, double-click the AuthorsService.asmx file to open it
in the designer.
2. On the Data menu, click Generate DataSet. In the Generate Dataset
dialog box, select New and name the dataset authors1. Do not select the
Add this dataset to the designer check box. Click OK.

Note A dataset schema file, authors1.xsd, is created and added to the

project. This schema file contains a class definition for authors1. This class,
which inherits from DataSet, contains a typed dataset definition for the
authors table.

3. On the File menu, click Save All.

38 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

! Add methods to the XML Web service

1. In Solution Explorer, double-click AuthorsService.asmx, if it is not
already open in the designer.
2. On the View menu, click Code.
3. Add a method named GetAuthors to deliver a dataset to the client.
This method creates a new authors1 dataset, and fills it by using the
SqlDataAdapter that is based on the authors table. The method then
returns the dataset:
The following code shows the method:
[WebMethod]
public authors1 GetAuthors()
{
authors1 authors = new authors1();
sqlDataAdapter1.Fill(authors);
return authors;
}

4. Add a method named UpdateAuthors to propagate changes from the client

back to the database.
This method has an authors1 dataset parameter (authorChanges) that
contains the changed data and updates the database through the
SqlDataAdapter.Update method. The Update method accepts the changes
in the dataset. The dataset is returned to the client. The client then uses this
returned dataset to update its own instance of the authors1 dataset.
The following code shows the method:
[WebMethod]
public authors1 UpdateAuthors(authors1 authorChanges)
{
if (authorChanges != null)
{
sqlDataAdapter1.Update(authorChanges);
return authorChanges;
}
else
{
return null;
}
}

Note In a production application, you would add error checking and

exception handling to these methods.

5. On the File menu, click Save All.

6. On the Build menu, click Build Solution.
7. To test the XML Web service, in the Solution Explorer right-click
AuthorsService.asmx and click View in Browser. In the browser, click
GetAuthors and in the resulting GetAuthors page, click the Invoke button.
You should see the list of authors displayed as XML.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 39

Exercise 2
Creating a Windows User Interface
In this exercise, you will create a Windows Forms client application. The
application consists of one Windows Form that contains a reference to
AuthorsWebService. The data in the database is displayed in a DataGrid
control when a Load button on the form is clicked.
To implement the display of data in the DataGrid, you call the XML Web
service’s GetAuthors method. The DataGrid control enables direct editing of
the data, with changes being passed directly to the underlying dataset.
In addition to a Load button, the form has a save button. The code for this
button calls the XML Web service's UpdateAuthors method to save the
changes back to the database.

! Create the Windows application

1. Open Visual Studio .NET and on the File menu, click New, and then click
Project to display the New Project dialog box.
2. Select Visual C# Projects in the Project Types pane, then select Windows
Application in the Templates pane.
3. Name the project AuthorsWinClient.
4. In the Location box, type the name of the Starter folder:
<install folder>\Labs\Lab16\Starter
5. Click OK.
The AuthorsWinClient project is created and Form1 is automatically
added to the project and appears in the Windows Forms Designer.
6. Add a reference to the XML Web service project that you created earlier.
a. In Solution Explorer, expand the AuthorsWinClient node, right-click
the References node, and on the shortcut menu, click Add Web
Reference.
b. In the Address box at the top of the Add Web Reference dialog box,
type the following and then press ENTER:
http://localhost/AuthorsWebService/AuthorsService.asmx
This is the location of the XML Web service file of your ASP.NET Web
Service project.
c. Click Add Reference.
You can now create an instance of the authors1 dataset in your
application.
40 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

! Add the controls to the form

1. Drag a DataGrid control from the Windows Forms tab of the Toolbox
onto the form.
2. Drag a Button control from the Windows Forms tab of the Toolbox onto
the form. Set the button's Name property to LoadData and its Text
property to Load.
3. Drag a second Button control from the Windows Forms tab of the
Toolbox onto the form. Set the button's Name property to SaveData and its
Text property to Save.
4. Drag a DataSet object from the Data tab of the Toolbox onto the form. In
the Add DataSet dialog box, select Typed dataset and then select
AuthorsWinClient.localhost.authors1 from the Name list. Click OK.
This action creates a DataSet object in the component tray that is based on
the authors1 dataset class definition.
5. Select the DataSet control and set the Name property to AuthorData.
6. Select the DataGrid control and select AuthorData from the DataSource
property list. Select authors from the DataMember property list.
The column headings of the DataGrid are set to the Authors table column
names.
You may want to adjust the width of the form and the DataGrid control to
accommodate all of the column headings. The user can then avoid having to
scroll horizontally to view all of the columns in the DataGrid.

! Add code for the LoadData and SaveData buttons

1. On the View menu, click Designer. Double-click the button that is labeled
Load to create an empty event handler for the Click event. Add the
following code to the LoadData_Click method:
private void LoadData_Click(
object sender, System.EventArgs e)
{
AuthorsWinClient.localhost.AuthorsService ws = new
AuthorsWinClient.localhost.AuthorsService();
ws.Credentials =
System.Net.CredentialCache.DefaultCredentials;
AuthorData.Merge(ws.GetAuthors());
}

XML Web service methods are called by first creating an instance of the
service class, and then calling the service methods. In this case, the
GetAuthors method is called. The dataset returned is merged with the
AuthorData dataset.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 41

2. On the View menu, click Designer. Double-click the button labeled Save to
create an empty event handler for the Click event. Add the following code
to the SaveData_Click method:
private void SaveData_Click(
object sender, System.EventArgs e)
{
if (AuthorData.HasChanges())
{
AuthorsWinClient.localhost.AuthorsService
ws = new
AuthorsWinClient.localhost.AuthorsService();
ws.Credentials =
System.Net.CredentialCache.DefaultCredentials;
AuthorsWinClient.localhost.authors1 diffAuthors =
new AuthorsWinClient.localhost.authors1();
diffAuthors.Merge(AuthorData.GetChanges());
ws.UpdateAuthors(diffAuthors);
AuthorData.Merge(diffAuthors);
}
}

If there are changes in the dataset, a new dataset of type authors1 is created
to hold just the changed data. This dataset is then passed to the XML Web
service's UpdateAuthors method. The dataset is returned with the changes
accepted, and the AuthorData dataset is updated to reflect these new
changes.

! Run the application

1. On the File menu, click Save All.
2. In Solution Explorer, right-click AuthorsWinClient, and click Set as
StartUp Project.
3. Press CTRL+F5 to run the application.
A window is displayed that contains an empty table with headers from the
authors table in the pubs database.
4. Click Load to populate the table. Make some changes to the data, and then
click Save.
You can click Load again to see that the changes that you made were stored
in the database. Also, close and reopen the application. The next time you
click Load, you will see that your changes have persisted.
42 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

" Accessing Data with DataReaders

Topic Objective
To introduce the topics in
this section.
! Creating a DataReader
Lead-in
Another method of ! Reading Data from a DataReader
accessing data from a data
source is to use ! Using DataSets vs. DataReaders
DataReaders.

*ILLEGAL FOR NON-TRAINER USE**

The benefit of using a DataSet is that it gives you a disconnected view of the
database. For long running applications, this is often the best approach. For
Web applications, developers usually perform short and simple operations with
each request, such as displaying data. For such operations, developers do not
have to maintain a DataSet object. In such cases, you can use a DataReader.

Choosing a DataReader or a DataSet

When deciding whether your application should use a DataReader or a
DataSet, you should consider the type of functionality that your application
requires. Use a DataSet when you need to do any of the following:
! Remote data between tiers or from an XML Web service.
! Interact with data dynamically such as binding to a Windows Forms control
or combining and relating data from multiple sources.
! Cache data locally in your application.
! Provide a hierarchical XML view of relational data and use tools like an
XSL Transformation or an XML Path Language (XPath) Query on your
data.
For more information, see XML and the DataSet in the .NET Framework
SDK documentation.
! Perform extensive processing on data without requiring an open connection
to the data source, which frees the connection to be used by other clients.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 43

If you do not require the functionality that is provided by the DataSet, you can
improve the performance of your application by using the DataReader to
return your data in a forward-only read-only fashion. Although the
DataAdapter uses the DataReader to fill the contents of a DataSet, by using
the DataReader instead, you can receive the following performance gains:
! The saving of memory that would be consumed by the DataSet.
! The saving of the processing that would be required to create and fill the
contents of the DataSet.

In this section, you will learn how to read data from a data source by using
DataReaders.
44 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

Creating a DataReader
Topic Objective ! Create and Open the Database Connection
To describe how to retrieve
data from a database by SqlConnection
SqlConnection mySqlConnection
mySqlConnection == new
new
using a DataReader. SqlConnection("server=(local)\\NetSDK;
SqlConnection("server=(local)\\NetSDK; !
!
Trusted_Connection=yes;database=northwind");
Trusted_Connection=yes;database=northwind");
Lead-in mySqlConnection.Open();
You can also use a mySqlConnection.Open();
DataReader object to read ! Create the DataReader From a Command Object
data from a database.
SqlCommand
SqlCommand mySqlCommand
mySqlCommand == new
new SqlCommand(
SqlCommand(
"select
"select * from customers", mySqlConnection);
* from customers", mySqlConnection);
SqlDataReader
SqlDataReader myReader
myReader ==
mySqlCommand.ExecuteReader();
mySqlCommand.ExecuteReader();

! Close the Reader and the Connection

If
If (myReader
(myReader !=
!= null)
null) myReader.Close();
myReader.Close();
if
if (mySqlConnection.State ==
(mySqlConnection.State == ConnectionState.Open)
ConnectionState.Open)
mySqlConnection.Close();
mySqlConnection.Close();
*****************************ILLEGAL FOR NON-TRAINER USE******************************
When a large amount of data is being retrieved, holding memory open becomes
an issue. For example, reading 10,000 rows out of a database causes a
DataTable to allocate and maintain memory for those 10,000 rows for the
lifetime of the table. If 1,000 users do this against the same server at the same
time, memory usage becomes critical.
To address such situations, the DataReader is designed to produce a read-only,
forward-only stream returned from the database. Only one record at a time is
ever in memory. There are two DataReader objects, the SqlDataReader and
the OleDbDataReader.
A DataReader keeps the connection open until the DataReader is closed.
To use a SqlDataReader, declare a SqlCommand instead of a
SqlDataAdapter. The SqlCommand exposes an ExecuteReader method that
takes a SqlDataReader as a parameter. Note that you must explicitly open and
close the SqlConnection when you use a SQLCommand.
SqlConnection mySqlConnection = new
SqlConnection("server=(local)\\NetSDK;!
Trusted_Connection=yes;database=northwind");
mySqlConnection.Open();

SqlCommand mySqlCommand = new SqlCommand(

"select * from customers", mySqlConnection);

SqlDataReader myReader = mySqlCommand.ExecuteReader();

//...
if (myReader != null)
myReader.Close();

if (mySqlConnection.State == ConnectionState.Open)
mySqlConnection.Close();
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 45

Error Handling with a DataReader

When using connections with the DataReader object, you should always use a
try/finally block to ensure that, if anything fails, connections will be closed.
SqlDataReader myReader = null;

SqlConnection mySqlConnection = new SqlConnection(

"server=(local)\\NetSDK;!
Trusted_Connection=yes;database=northwind");
SqlCommand mySqlCommand = new SqlCommand(
"select * from customers", mySqlConnection);

try
{
mySqlConnection.Open();
myReader = mySqlCommand.ExecuteReader();
//…
}
catch(Exception e)
{
Console.WriteLine(e.ToString());
}
finally
{
if (myReader != null)
myReader.Close();

if (mySqlConnection.State == ConnectionState.Open)
mySqlConnection.Close();
}
46 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

Reading Data from a DataReader

Topic Objective
To explain how to read data
! Call Read for Each Record
from a DataReader.
Lead-in # Returns false when there are no more records
After you have called the
ExecuteReader method of ! Get Field(s)
the Command object, you
access a record in the
# Parameter is the ordinal position or name of the field
DataReader by calling the while
while (myReader.Read())
(myReader.Read())
Read method. {{
Console.Write(myReader["CustomerID"].ToString()
Console.Write(myReader["CustomerID"].ToString() ++
"" ");
");
Console.WriteLine(myReader["CompanyName"].ToString());
Console.WriteLine(myReader["CompanyName"].ToString());
}}

! Call Close to Free Up the Reader and the Connection

*ILLEGAL FOR NON-TRAINER USE**

After you have called the ExecuteReader method of the Command object, you
access a record in the DataReader by calling the Read method. The default
positioning in the DataReader is before the first record, therefore you must call
Read before accessing any data. When no more records are available, the Read
method returns a null value.

Reading Fields from the Current Record

To get the data from fields in the current record, call an appropriate Get
method, for example, GetDateTime, GetDouble, GetInt32, or GetString. The
parameter of the Get method is the ordinal value of the field that you want to
read. For example, the following code reads the CustomerID and
CompanyName fields, from the current record of the DataReader, by using the
GetString method:
string customerID = myReader.GetString(0);
string companyName = myReader.GetString(1);

You can also reference the fields of data in the current record of the data reader
by name, and then call an appropriate conversion function, as shown in the
following example code:
string customerID = myReader["CustomerID"].ToString();
string companyName = myReader["CompanyName"].ToString();
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 47

Looping Through All Records

To loop through and output to the Console all the records in a DataReader, you
can use a While loop, as shown in the following sample code:
while (myReader.Read())
{
Console.Write(myReader["CustomerID"].ToString() +
" ");
Console.WriteLine(myReader["CompanyName"].ToString());
}

Closing the DataReader

While the DataReader is in use, the associated connection is busy serving the
DataReader. Therefore, you must call Close to close the DataReader when
you are finished using it.
if (myReader != null)
myReader.Close();

if (mySqlConnection.State == ConnectionState.Open)
mySqlConnection.Close();
48 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

Demonstration: Accessing Data Using DataReaders

Topic Objective
To introduce the
demonstration.
Lead-in
In this demonstration, you
will see how to read data
from a database by using a
SqlDataReader.

*ILLEGAL FOR NON-TRAINER USE**

In this demonstration, you will see how to read data from a database by using a
SQLDataReader.
Run the Visual Studio .NET DataReader project from the following location:
<install folder>\Democode\Mod16\Demo16.4
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 49

Using DataSets vs. DataReaders

Topic Objective
To describe the different DataSet DataReader
processes for getting data
with a DataSet versus a 1. Create a database 1. Create a database connection
DataReader. connection
2. Open the database connection
Lead-in 2. Store query in DataAdapter
3. Store query in SqlCommand
The procedure for accessing
3. Populate DataSet with
databases from ASP.NET is Fill method 4. Populate DataReader with
different depending on ExecuteReader method
whether you use a DataSet 4. Create DataView
or a DataReader. 5. Call Read for each record,
5. Bind DataView to and Get for each field
list-bound control
6. Manually display data
7. Close the DataReader and
the connection

*ILLEGAL FOR NON-TRAINER USE**

The general procedure for accessing databases from ASP.NET is different
Delivery Tip depending on whether you will be using a DataSet or a DataReader:
Discuss performance issues
in DataReaders and Using DataSets Using DataReaders
DataSets.
1. Connect to the database by using 1. Connect to the database by using
SqlConnection or OleDbConnection. SqlConnection or OleDbConnection.
2. Store the database query in 2. Open the connection with the Open
SqlDataAdapter or method.
OleDbDataAdapter objects.
3. Populate a DataSet from the 3. Store database query in SqlCommand
DataAdapter by using Fill. or OleDbCommand objects.
4. Set up a new DataView for the 4. Populate a DataReader from the
desired table. Command by using ExecuteReader
method.
5. Bind a server control, such as the 5. Call Read and Get methods of the
DataGrid, to the DataView. DataReader to read data.
6. Manually display data.
7. Close the DataReader. and the
connection.
50 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

" Binding to XML Data

Topic Objective
To introduce the topics
included in this section.
! Overview of XML
Lead-in
Another common source of ! Reading XML Data into a DataSet
data for applications is XML
documents.

*ILLEGAL FOR NON-TRAINER USE**

HTML is widely used for presenting information on the Web. HTML works
well as a presentation language, but it is not suitable for representing data. For
example, you can easily format data in an HTML table, but you cannot describe
the individual components of the information. To share information between
applications, you must have a language that can describe data in a standardized
way so that any application, present or future, can understand and use this data
correctly. XML is one such standardized language. XML not only helps you
structure your data but acts as a common language between different business
applications.
In this section, you will get an overview of XML. You will also learn how to
read and display XML data by using ADO.NET.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 51

Overview of XML
Topic Objective
To provide an overview of
XML data.
! Machine-Readable and Human-Readable Data
Lead-in
XML is a common language ! Defines the Data Content and Structure
used for exchanging
information between ! Separates Structure from Presentation
business applications.
! Allows You to Define Your Own Tags and Attributes

*ILLEGAL FOR NON-TRAINER USE**

Businesses today face many problems when it comes to organizing data. They
need to meet the following requirements:
! Data must be readable by both computers and users.
! Both the content and the structure of the data must be defined.
! The structure of the data needs to be separate from the presentation of the
data.
! The structure needs to be open and extensible.

XML fulfills all of these requirements.

XML defines the structure of data in an open and self-describing manner. This
allows data to be easily transferred over a network and consistently processed
by the receiver. XML describes how data is structured, not how it should be
displayed or used. XML documents contain tags that assign meaning to the
content of the document. These tags allow programmers to find the data they
need in the XML document.
For example, the following XML sample contains information about an
employee but does not specify how to display this information:
<employee>
<name>Jake</name>
<salary>25000</salary>
<region>Ohio</region>
</employee>
52 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

XML is considered a markup language because it allows you to define data

structure by using markup tags. You can define your own tags that describe the
data in whatever way you find useful.
XML data is held in a simple, open format that is easily parsed by other
applications. The fact that XML documents contain text rather than binary data
is another key advantage. Applications can parse an XML document, looking
for specific tags of interest to those applications. Unknown tags and their
associated data can be freely ignored.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 53

Reading XML Data into a DataSet

Topic Objective
To explain how to read XML
data into a DataSet.
! Setup the XML file for reading
Lead-in
Because XML is an FileStream
FileStream fs
fs == File.OpenRead("myFile.xml");
File.OpenRead("myFile.xml");
important part of ASP.NET, StreamReader
StreamReader myStreamReader
myStreamReader == new
new StreamReader(fs);
StreamReader(fs);
there are various easy ways
to bind to XML data. ! Read the contents of the File into a DataSet
DataSet
DataSet myDataSet
myDataSet == new
new DataSet();
DataSet();
myDataSet.ReadXml(myStreamReader);
myDataSet.ReadXml(myStreamReader);

! Bind a DataGrid to the DataSet

dataGrid1.DataSource
dataGrid1.DataSource == myDataSet.Tables[0];
myDataSet.Tables[0];

*ILLEGAL FOR NON-TRAINER USE**

DataSets in ADO.NET are designed to extract data in a way that is independent
of its data source. Therefore, reading data from an XML source is similar to
reading data from a database. To read XML data, you import the System.IO
namespace in your ASP.NET page.

Note You cannot read XML data into a DataReader. You can read it only into
a DataSet.

For XML data, the DataSet supports a ReadXml method that takes a
FileStream as its parameter. The DataSet expects data to be in the following
format:
<DocumentElement>
<TableName>
<ColumnName1>column value</ColumnName1>
<ColumnName2>column value</ColumnName2>
<ColumnName3>column value</ColumnName3>
</TableName>
<TableName>
<ColumnName1>column value</ColumnName1>
<ColumnName2>column value</ColumnName2>
<ColumnName3>column value</ColumnName3>
</TableName>
</DocumentElement>

Each TableName section corresponds to a single row in the table.

54 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

The following example shows how to read the schema and data from an XML
file by using the ReadXml method, the FileStream object, and the
StreamReader object. Note that after the data is read into the DataSet, it is
indistinguishable from SQL data—the DataGrid binds to it in the same way.
You can perform the following steps to read a file named myFile.xml that
contains XML data and displays it in a DataGrid.
First open the XML file and create a StreamReader:
FileStream fs = File.OpenRead("myFile.xml");
StreamReader myStreamReader = new StreamReader(fs);

Next, read the XML data into the DataSet:

DataSet myDataSet = new DataSet();
myDataSet.ReadXml(myStreamReader);

Finally, bind a DataGrid to the DataSet:

dataGrid1.DataSource = myDataSet.Tables[0];

After the data has been read into a DataSet, the repeated elements in the XML
become the columns in the DataSet and can be bound to any control to be
displayed on the client.
The Windows Forms code, including try/catch/finally blocks, that is used in
Demonstration: Reading XML Data into a DataSet, is as follows:
StreamReader myStreamReader = null;
statusBar1.Text = "";

try
{
FileStream fs = File.OpenRead(textBox1.Text);
myStreamReader = new StreamReader(fs);
DataSet myDataSet = new DataSet();
myDataSet.ReadXml(myStreamReader);
dataGrid1.DataSource = myDataSet.Tables[0];
statusBar1.Text = "Read file: " + textBox1.Text;
}
catch(Exception exception)
{
statusBar1.Text = exception.ToString();
}
finally
{
if (myStreamReader != null) myStreamReader.Close();
}
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 55

Demonstration: Reading XML Data into a DataSet

Topic Objective
To demonstrate how to
display information from an
XML file.
Lead-in
In this demonstration, you
will see how to read
information from an XML file
and display it in a DataGrid
control.

*ILLEGAL FOR NON-TRAINER USE**

In this demonstration, you will see how to read information from an XML file
and display it in a DataGrid control.
Run the Visual Studio .NET XMLData project from the following location:
<install folder>\Democode\Mod16\Demo16.5
Enter the default filename books1.xml and click the Load Data button. The file
books1.xml is read into a DataSet and displayed in a DataGrid.
56 Module 16 (Optional): Using Microsoft ADO.NET to Access Data

Review
Topic Objective
To reinforce module
objectives by reviewing key
points. ! Overview of ADO.NET
Lead-in ! Connecting to a Data Source
The review questions cover
some of the key concepts ! Accessing Data with DataSets
taught in the module.
! Using Stored Procedures
! Accessing Data with DataReaders
! Binding to XML Data

*ILLEGAL FOR NON-TRAINER USE**

1. What are some of the new objects in the ADO.NET object model?
Some of the new objects in the ADO.NET object model are: DataSet,
DataAdapter, DataView, DataReader, and DataTable.

2. What is the difference between a DataSet and a DataView?

DataSet is a collection of DataTables and a DataView is a custom view
of the DataTables in a DataSet.

3. What is the difference between a DataSet and a DataReader?

The DataReader is designed to produce a read-only, forward-only
stream returned from the database.
The DataSet is designed to handle the actual data from a data store. It
represents a cache of data, with database-like behavior. It can contain
tables, columns, relationships, constraints, and data.
Module 16 (Optional): Using Microsoft ADO.NET to Access Data 57

4. What is the purpose of the DataAdapter object?

A DataAdapter object is a tool that is used to create and initialize
various tables. It allows for the retrieval and saving of data between a
DataSet object and the source data store. It is responsible for pulling
out data from the physical store and pushing it into data tables and
relations.

5. Which method is used to populate a DataSet with results of a query?

The method that is used to populate the DataSet with results of a query
is the Fill method.
THIS PAGE INTENTIONALLY LEFT BLANK
Module 17 (Optional):
Attributes

Contents

Overview 1
Overview of Attributes 2
Defining Custom Attributes 13
Retrieving Attribute Values 22
Demonstration: Custom Attributes 26
Lab 17: Defining and Using Attributes 27
Review 36
Information in this document, including URL and other Internet Web site references, is subject to
change without notice. Unless otherwise noted, the example companies, organizations, products,
domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious,
and no association with any real company, organization, product, domain name, e-mail address,
logo, person, places or events is intended or should be inferred. Complying with all applicable
copyright laws is the responsibility of the user. Without limiting the rights under copyright, no
part of this document may be reproduced, stored in or introduced into a retrieval system, or
transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or
otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft, ActiveX, BizTalk, IntelliMirror, Jscript, MSDN, MS-DOS, MSN, PowerPoint,

The names of actual companies and products mentioned herein may be the trademarks of their
respective owners.
Module 17 (Optional): Attributes iii

Instructor Notes
Presentation: Teach this module if time permits. Module 17 is a stand-alone module that is
60 Minutes not dependent upon any other module.
Lab: This module provides students with the details about how to use attributes in
45 Minutes code. It describes the predefined attributes that are provided by the Microsoft®
.NET Framework and provides some simple examples of how to use some
common attributes. The concept of custom attributes is introduced. This
introduction is followed by a detailed explanation of how to define and use
custom attributes. The process used to compile code that has custom attributes
is also explained. Finally, the module describes how to retrieve attribute values
during run time by using reflection. The procedure that is used to retrieve
attribute information into an array and query the array to obtain the required
values is explained.
After completing this module, students will be able to:
! Use common predefined attributes.
! Create simple custom attributes.
! Query attribute information at run time.

Materials and Preparation

This section provides the materials and preparation tasks that you need to teach
this module.

Required Materials
To teach this module, you need Microsoft PowerPoint® file 2349B_17.ppt.

Preparation Tasks
To prepare for this module, you should:
! Read all of the materials for this module.
! Complete the lab.
! Read the instructor notes and margin notes for the module.
! Practice using the Microsoft Intermediate Language disassembler to
examine the metadata of an assembly.
iv Module 17 (Optional): Attributes

Demonstration
This section provides demonstration procedures that will not fit in the margin
notes or are not appropriate for the student notes.
Use the debugger to step through the code while you point out features and ask
students what they think will happen next.

Custom Attributes
In this demonstration, you will show students how to declare and apply custom
attributes and how to use reflection to retrieve custom attribute metadata.
The code for this demonstration is contained in one project and is located in
<install folder>\Democode\Mod17.

Module Strategy
Use the following strategy to present this module:
! Overview of Attributes
Begin by explaining that attributes are only annotations to classes and
perform no function themselves. Before attributes can cause an action,
certain code must be implemented. This code is in the runtime for the
predefined attributes and is written by the developer for custom attributes.
Explain the syntax used to apply an attribute, and, after covering the lists of
predefined attributes briefly, discuss the three attributes—Conditional,
DllImport, and Transaction—using examples.
! Defining Custom Attributes
Introduce the need for creating custom attributes, and explain the procedures
involved in defining a custom attribute. Explain the use of AttributeUsage
and how to create an attribute class. Then explain the details of the
procedure used to compile code that uses custom attributes. Finish the
section by explaining how to use multiple attributes in code.
! Retrieving Attribute Values
In this section, introduce the concept of retrieving attribute values at run
time by using reflection. Explain how to use the MemberInfo class and the
typeof operator to obtain attribute values. Finally, discuss how to iterate
through the stored attribute values in an array to retrieve the required values.
To end the discussion about attributes, use the review slide to recapitulate
the main concepts covered in the module.
Module 17 (Optional): Attributes 1

Overview
Topic Objective
To provide an overview of
the module topics and
objectives.
! Overview of Attributes
Lead-in ! Defining Custom Attributes
In this module, you will learn
about using attributes in ! Retrieving Attribute Values
Microsoft Visual C# .NET.

*ILLEGAL FOR NON-TRAINER USE**

Attributes are a simple technique for adding metadata to classes. They can be
Delivery Tip useful when you need to build components.
Teach this module if time
permits. This is a stand- In this module, you will learn the purpose of attributes and the function that
alone module that is not they perform in Microsoft® Visual C#™ .NET applications. You will learn about
dependent upon any other
attribute syntax and how to use some of the predefined attributes in the
module.
Microsoft .NET Framework environment. You will also learn to create custom
user-defined attributes. Finally, you will learn how classes and other object
types can implement and use these custom attributes to query attribute
information at run time.
After completing this module, you will be able to:
! Use common predefined attributes.
! Create simple custom attributes.
! Query attribute information at run time.
2 Module 17 (Optional): Attributes

" Overview of Attributes

Topic Objective
To introduce the topics
covered in this section.
! Introduction to Attributes
Lead-in
In this section, you will learn ! Applying Attributes
what attributes are and how
they are used. ! Common Predefined Attributes
! Using the Conditional Attribute
! Using the DllImport Attribute
! Using the Transaction Attribute

*ILLEGAL FOR NON-TRAINER USE**

With the introduction of attributes, the C# language provides a convenient
technique that will help handle tasks such as changing the behavior of the
runtime, obtaining transaction information about an object, conveying
organizational information to a designer, and handling unmanaged code.
After completing this lesson, you will be able to:
! Identify which tasks you can perform with attributes.
! Use the syntax for using attributes in your code.
! Identify some of the predefined attributes that are available in the .NET
Framework.
Module 17 (Optional): Attributes 3

Introduction to Attributes
Topic Objective
To define attributes.
Lead-in ! Attributes Are:
The concept of an attribute
is simple. # Declarative tags that convey information to the runtime
# Stored with the metadata of the element

! .NET Framework Provides Predefined Attributes

# The runtime contains code to examine values of
attributes and act on them

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework provides attributes so that you can extend the capabilities
Delivery Tip of the C# language. An attribute is a declarative tag that you use to convey
Stress that attributes are information to the runtime about the behavior of programmatic elements such
fundamentally a very simple as classes, enumerators, and assemblies.
idea—they are simply
annotations for your code You can think of attributes as annotations that your programs can store and use.
that are intended to convey In most cases, you write the code that retrieves the values of an attribute in
useful declarative addition to the code that performs a change in behavior at run time. In its
information. simplest form, an attribute is an extended way to document your code.
You can apply attributes to many elements of the source code. Information
about the attributes is stored with the metadata of the elements they are
associated with.
The .NET Framework is equipped with a number of predefined attributes. The
code to examine them and act upon the values they contain is also incorporated
as a part of the runtime and .NET Framework software development kit (SDK).
4 Module 17 (Optional): Attributes

Applying Attributes
Topic Objective
To explain the syntax for
using attributes. ! Syntax: Use Square Brackets to Specify an Attribute
Lead-in
[attribute(positional_parameters,named_parameter=value,
[attribute(positional_parameters,named_parameter=value, ...)]
...)]
Attributes can be applied to
element
element
several different types of
programming elements.
! To Apply Multiple Attributes to an Element, You Can:
# Specify multiple attributes in separate square brackets
# Use a single square bracket and separate attributes with
commas
# For some elements such as assemblies, specify the
element name associated with the attribute explicitly

*ILLEGAL FOR NON-TRAINER USE**

You can apply attributes to different kinds of programming elements. These
elements include assemblies, modules, classes, structs, enums, constructors,
methods, properties, fields, events, interfaces, parameters, return values, and
delegates.
Attribute Syntax
To specify an attribute and associate it with a programming element, use the
following general syntax:
[attribute(positional_parameters,name_parameter=value, ...)]
element

You specify an attribute name and its values within square brackets ([ and ])
before the programmatic element to which you want to apply the attribute. Most
attributes take one or more parameters, which can be either positional or
named.
You specify a positional parameter in a defined position in the parameter list, as
you would specify parameters for methods. Any named parameter values
follow the positional parameters. Positional parameters are used to specify
essential information, whereas named parameters are used to convey optional
information in an attribute.

Tip Before using an unfamiliar attribute, it is a good practice to check the

documentation for the attribute to find out which parameters are available and
whether they should be positional or named.
Module 17 (Optional): Attributes 5

Example
As an example of using attributes, consider the following code, in which the
DefaultEvent attribute is applied on a class by using a positional string
parameter, ShowResult:
[DefaultEvent("ShowResult")]
public class Calculator: System.Windows.Forms.UserControl
{
...
}

Applying Multiple Attributes

You can apply more than one attribute to an element. You can enclose each
attribute in its own set of square brackets, although you can also enclose
multiple attributes, separated with commas, in the same set of square brackets.
In some circumstances, you must specify exactly which element an attribute is
associated with. For example, in the case of assembly attributes, place them
after any using clauses but before any code, and explicitly specify them as
attributes of the assembly.
The following example shows how to use the CLSCompliant assembly
attribute. This attribute indicates whether or not an assembly strictly conforms
to the Common Language Specification.
using System;
[assembly:CLSCompliant(true)]

class MyClass
{
...
}
6 Module 17 (Optional): Attributes

Common Predefined Attributes

Topic Objective
To list some common
predefined attributes.
! .NET Provides Many Predefined Attributes
Lead-in
The .NET Framework # General attributes
provides a large number of
predefined attributes. # COM interoperability attributes
# Transaction handling attributes
# Visual designer component-building attributes

*ILLEGAL FOR NON-TRAINER USE**

The capabilities of predefined attributes in the .NET Framework encompass a
wide range of areas, from interoperability with COM to compatibility with
visual design tools.
This topic describes some of the common predefined attributes that are
provided by the .NET Framework. However, it is not intended to be
comprehensive. For more information about predefined attributes, refer to the
Microsoft Visual Studio® .NET documentation.

General Attributes
The following list summarizes some of the general attributes that are provided
by the .NET Framework.
Attribute Applicable to Description

Conditional Method Tests to see whether a named

symbol is defined. If it is
defined, any calls to the method
are executed normally. If the
symbol is not defined, the call
is not generated.
DllImport Method Indicates that the method is
implemented in unmanaged
code, in the specified DLL. It
causes the DLL to be loaded at
run time and the named method
to execute.
SecurityPermissionAttributes Assembly, Allows security actions for
Class, Struct, SecurityPermission to be
Constructor, applied to code using
Method declarative security.
Module 17 (Optional): Attributes 7

Delivery Tip COM Interoperability Attributes

Avoid getting into long When using the attributes to provide interoperability with COM, the goal is to
conversations about COM, ensure that using COM components from the managed .NET Framework
transactions, and environment is as seamless as possible. The .NET Framework has many
interoperability because this attributes relating to COM interoperability. Some of these are listed in the
is beyond the scope of this
following table.
module. This information is
presented to show that the Attribute Applicable to Description
.NET Framework is
compatible with COM. Tell ComImport Class/Interface Indicates that a class or interface
students that COM and definition was imported from a COM
interoperability is covered in type library.
depth in Module 15,
“Interoperating Between ComRegisterFunction Method Specifies the method to be called when
Managed and Unmanaged a .NET Framework assembly is
Code,” in this course. registered for use from COM.
ComUnregisterFunction Method Specifies the method to be called when
a .NET assembly is unregistered for use
from COM.
DispId Method, field, Indicates which dispatch ID is to be
property used for the method, field, or property.
In parameter Indicates that the data should be
marshaled from the caller to the callee.
MarshalAs Field, Specifies how data should be marshaled
parameter, between COM and the managed
return values environment.
ProgId Class Specifies which prog ID is to be used
for the class.
Out parameter Indicates that data should be marshaled
from the callee back to caller.
InterfaceType Interface Specifies whether a managed interface
is IDispatch, IUnknown, or Dual when
it is exposed to COM.

For more information about COM interoperability, see Module 15,

“Interoperating Between Managed and Unmanaged Code,” in Course 2349B,
Programming with the Microsoft .NET Framework (Microsoft Visual C# .NET),
or search for "Microsoft ComServices" in the .NET Framework SDK.

Transaction Handling Attributes

Components running in a COM+ environment use transaction management.
The attribute you use for this purpose is shown in the following table.
Attribute Applicable to Description

Transaction Class Specify the type of transaction that should be

available to this object.
8 Module 17 (Optional): Attributes

Visual Designer Component-Building Attributes

Developers who build components for a visual designer use the attributes listed
in the following table.
Attribute Applicable to Description

Bindable Property Specifies whether a property is typically used

for binding.
DefaultProperty Class Specifies the default property for the
component.
DefaultValue Property Indicates that the property is the default value
for the component.
Localizable Property When code is generated for a component,
members that are marked with
Localizable(true) have their property values
saved in resource files. You can localize these
resource files without modifying the code.
DefaultEvent Class Specifies the default event for the component.
Category Property, Specifies the category into which the visual
event designer should place this property or event in
the property window.
Description Property, Defines a brief piece of text to be displayed at
event the bottom of the property window in the visual
designer when this property or event is selected.
Module 17 (Optional): Attributes 9

Using the Conditional Attribute

Topic Objective
To show how to use the ! Serves As a Debugging Tool
Conditional attribute. # Causes conditional compilation of method calls, depending on the
Lead-in value of a programmer-defined symbol
The Conditional attribute is # Does not cause conditional compilation of the method itself
frequently used for
class
class MyClass
debugging classes. MyClass
{{
[Conditional
[Conditional ("DEBUGGING")]
("DEBUGGING")]
public
public static
static void
void MyMethod(
MyMethod( ))
{{
...
...
! Restrictions on Methods }}
}}
# Must have return type of void
# Must not be declared as override
# Must not be from an inherited interface

*ILLEGAL FOR NON-TRAINER USE**

You can use the Conditional attribute as a debugging aid in your C# code. This
Delivery Tip attribute causes conditional compilation of method calls, depending on the
The Conditional attribute is
common and is used in the
value of a symbol that you define. It lets you invoke methods that, for example,
labs. Make sure students display the values of variables, while you test and debug code. After you have
understand how to use it. debugged your program, you can “undefine” the symbol and recompile your
code without changing anything else. (Or you can simply remove the symbol
from the command line, and not change anything.)

Example
The following example shows how to use the Conditional attribute. In this
example, the MyMethod method in MyClass is tagged with the Conditional
attribute by the symbol DEBUGGING:
class MyClass
{
[Conditional ("DEBUGGING")]
public static void MyMethod( )
{
...
}
}
10 Module 17 (Optional): Attributes

The symbol DEBUGGING is defined as follows:

#define DEBUGGING

class AnotherClass
{
public static void Test( )
{
MyClass.MyMethod( );
}
}

As long as the symbol DEBUGGING remains defined when the method call is
compiled, the method call will operate normally. When DEBUGGING is
undefined, the compiler will omit calls to the method. Therefore, when you run
the program, it will be treated as though that line of code does not exist.
You can define the symbol in one of two ways. You can either add a #define
directive to the code as shown in the preceding example, or define the symbol
from the command line when you compile your program.

Restrictions on Methods
The methods to which you can apply a Conditional attribute are subject to a
number of restrictions. In particular, they must have a return type of void, they
must not be marked as override, and they must not be the implementation of a
method from an inherited interface.

Note The Conditional attribute does not cause conditional compilation of the
method itself. The attribute only determines the action that will occur when the
method is called. If you require conditional compilation of a method, then you
must use the #if and #endif directives in your code.
Module 17 (Optional): Attributes 11

Using the DllImport Attribute

Topic Objective
To explain how to use the
DllImport attribute.
! With the DllImport Attribute, You Can:
Lead-in
The DllImport attribute is # Invoke unmanaged code in DLLs from a C# environment
used to handle unmanaged
code. # Tag an external method to show that it resides in an
unmanaged DLL
[DllImport("MyDLL.dll",
[DllImport("MyDLL.dll", EntryPoint=“MyFunction")]
EntryPoint=“MyFunction")]
public
public static
static extern
extern int
int MyFunction(string
MyFunction(string param1);
param1);

public
public class
class MyClass(
MyClass( ))
{{
...
...
int
int result
result == MyFunction("Hello
MyFunction("Hello Unmanaged
Unmanaged Code");
Code");
...
...
}}

*ILLEGAL FOR NON-TRAINER USE**

You can use the DllImport attribute to invoke unmanaged code in your C#
programs. Unmanaged code is the term used for code that has been developed
outside the .NET environment (that is, standard C compiled into DLL files). By
using the DllImport attribute, you can invoke unmanaged code residing in
dynamic-link libraries (DLLs) from your managed C# environment.

Invoking Unmanaged Code

The DllImport attribute allows you to tag an extern method as residing in an
unmanaged DLL. When your code calls this method, the common language
runtime locates the DLL, loads it into the memory of your process, marshals
parameters as necessary, and transfers control to the address at the beginning of
the unmanaged code. This is unlike a normal program, which does not have
direct access to the memory that is allocated to it. The following code provides
an example of how to invoke unmanaged code:
[DllImport("MyDLL.dll", EntryPoint="MyFunction")]
public static extern int MyFunction(string param1);

public class MyClass( )

{
...
int result = MyFunction("Hello Unmanaged Code");
...
}
12 Module 17 (Optional): Attributes

Using the Transaction Attribute

Topic Objective
To show how to use the
Transaction attribute.
! To Manage Transactions in COM+
Lead-in
The Transaction attribute is # Specify that your component be included when a
used to manage transaction commit is requested
transactions.
# Use a Transaction attribute on the class that implements
the component
using
using EnterpriseServices;
EnterpriseServices;
...
...
[Transaction(TransactionOption.Required)]
[Transaction(TransactionOption.Required)]
public
public class
class MyTransactionalComponent
MyTransactionalComponent :: ServicedComponent
ServicedComponent
{{
...
...
}}

*ILLEGAL FOR NON-TRAINER USE**

It is likely that, as a Microsoft Visual Basic® or C++ developer working in a
Microsoft environment, you are familiar with technologies such as COM+. An
important feature of COM+ is that it allows you to develop components that can
participate in distributed transactions, which are transactions that can span
multiple databases, machines, and components.

Managing Transactions in COM+

Writing code to guarantee a correct transaction commit in a distributed
environment is difficult. However, if you use COM+, it takes care of managing
the transactional integrity of the system and coordinating events on the network.
In this case, you only need to specify that your component be included when an
application that uses your component requests a transaction commit. To make
this specification, you can use a Transaction attribute on the class that
implements the component, as follows:
using EnterpriseServices;
...
[Transaction(TransactionOption.Required)]
public class MyTransactionalComponent : ServicedComponent
{
...
}

The Transaction attribute is one of the predefined .NET Framework attributes

that the .NET Framework runtime interprets automatically.
Module 17 (Optional): Attributes 13

" Defining Custom Attributes

Topic Objective
To introduce the topics
covered in this section.
! Defining Custom Attribute Scope
Lead-in
You can define your own ! Defining an Attribute Class
custom attributes.
! Processing a Custom Attribute
! Using Multiple Attributes

*ILLEGAL FOR NON-TRAINER USE**

When you encounter a situation in which none of the predefined .NET
Framework attributes satisfy your requirements, you can create your own
attribute. Such a custom attribute will provide properties that allow you to store
and retrieve information from the attribute.
Like predefined attributes, custom attributes are objects that are associated with
one or more programmatic elements. They are stored with the metadata of their
associated elements, and they provide mechanisms for a program to retrieve
their values.
After completing this lesson, you will be able to:
! Define your own custom attributes.
! Use your own custom attributes.
14 Module 17 (Optional): Attributes

Defining Custom Attribute Scope

Topic Objective
To describe the scope of a ! Use the AttributeUsage Tag to Define Scope
custom attribute.
# Example
Lead-in
You need to scope your
[AttributeUsage(AttributeTargets.Method)]
[AttributeUsage(AttributeTargets.Method)]
custom attribute to define public
the elements that can use public class
class MyAttribute:
MyAttribute: System.Attribute
System.Attribute
{{ ...
... }}
your custom attribute.

! Use the Bitwise “or” Operator (|) to Specify

Multiple Elements
# Example
[AttributeUsage(AttributeTargets.Class
[AttributeUsage(AttributeTargets.Class || AttributeTargets.Struct)]
AttributeTargets.Struct)]
public
public class
class MyAttribute:
MyAttribute: System.Attribute
System.Attribute
{{ ... }
... }

*ILLEGAL FOR NON-TRAINER USE**

As with some predefined attributes, you must explicitly specify the
programming element to which you want to apply a custom attribute. To do so,
you annotate your custom attribute with an AttributeUsage tag as shown in the
following example:
[AttributeUsage(target_elements)]
public class MyAttribute: System.Attribute
{ ... }

Defining Attribute Scope

The parameter to AttributeUsage contains values from the
System.AttributeTargets enumeration to specify how the custom attribute can
be used. The members of this enumeration are summarized in the following
table.
Member name Attribute can be applied to

All Any element

Assembly assembly
Class class
Constructor constructor
Delegate delegate
Enum enum
Event event
Field field
Interface interface
Method method
Module module
Module 17 (Optional): Attributes 15

(continued)
Member name Attribute can be applied to

Parameter parameter
Property property
ReturnValue return value
Struct struct

Example of Using Custom Attributes

To specify that the MyAttribute custom attribute can be applied only to
methods, use the following code:
[AttributeUsage(AttributeTargets.Method)]
public class MyAttribute: System.Attribute
{
...
}

Specifying Multiple Elements

If the attribute can be applied to more than one element type, use the bitwise
“or” operator (|) to specify multiple target types. For example, if MyAttribute
can also be applied to constructors, the earlier code will be modified as follows:
[AttributeUsage(AttributeTargets.Method |
!AttributeTargets.Constructor)]
public class MyAttribute: System.Attribute
{
...
}

If a developer attempts to use MyAttribute in a context different than that

which is defined by AttributeUsage, the developer’s code will not compile.
16 Module 17 (Optional): Attributes

Defining an Attribute Class

Topic Objective
To describe what attribute
classes are and how they ! Deriving an Attribute Class
are defined.
# All attribute classes must derive from System.Attribute,
Lead-in directly or indirectly
To define custom attributes,
you must first define an # Suffix name of attribute class with “Attribute”
attribute class.
! Components of an Attribute Class
# Define a public constructor for the attribute class whose
arguments are the required positional parameters
# Use non-static public read-write properties for optional
named parameters

*ILLEGAL FOR NON-TRAINER USE**

After you define the scope of a custom attribute, you need to specify the way
Delivery Tip you want the custom attribute to behave. For this purpose, you must define an
Use the terminology
carefully. Talking about
attribute class. Such a class will define the name of the attribute, how it can be
attributes having attributes created, and the information that it will store.
could be confusing to some
The .NET Framework SDK provides a base class, System.Attribute that you
students.
must use to derive custom attribute classes and to access the values held in
Key Points custom attributes.
1. Always append the suffix
“Attribute” to the end of
custom attribute classes. Deriving an Attribute Class
2. Custom attribute classes All custom attribute classes must derive from System.Attribute, either directly
must descend from or indirectly. The following code provides an example:
System.Attribute.
public class DeveloperInfoAttribute: System.Attribute
{
...
public DeveloperInfoAtribute(string developer)
public string Date
{
get { ... }
set { ... }
}
}

It is a good practice to append the name of a custom attribute class with the
suffix “Attribute,” as in DeveloperInfoAttribute. This makes it easier to
distinguish the attribute classes from the non-attribute classes.
Module 17 (Optional): Attributes 17

Components of an Attribute Class

All attribute classes must have a constructor. For example, the DeveloperInfo
attribute requires the name of the developer as a string parameter; it therefore
has a constructor that accepts a string parameter. A custom attribute must define
a single constructor that sets the mandatory information. The positional
parameter or parameters of the attribute pass this information to the constructor.
An attribute class can allow for optional values by declaring non-static public
read-write properties or fields. You can specify these optional values as named
parameters when using the attribute.
For example, the following DeveloperInfoAttribute provides the required
developer name, Bert, as a positional parameter and specifies the optional Date
parameter, “08-28-2001” as a named parameter:
[DeveloperInfoAttribute("Bert", Date="08-28-2001")]
public class MyClass
{
...
}
18 Module 17 (Optional): Attributes

Processing a Custom Attribute

Topic Objective
To describe how the
compiler processes a ! The Compilation Process
custom attribute.
1. Searches for the Attribute Class
Lead-in
In this topic, you will see the 2. Checks the Scope of the Attribute
process that occurs when
the compiler encounters an 3. Checks for a Constructor in the Attribute
attribute on a program
element. 4. Creates an Instance of the Object
5. Checks for a Named Parameter
6. Sets Field or Property to Named Parameter Value
7. Saves Current State of Attribute Class

*ILLEGAL FOR NON-TRAINER USE**

When the compiler encounters an attribute on a programming element, the
compiler uses the following process to determine how to apply the attribute:
1. Searches for the attribute class
2. Checks the scope of the attribute
3. Checks for a constructor in the attribute
4. Creates an instance of the object
5. Checks for a named parameter
6. Sets the field or property to a named parameter value
7. Saves the current state of the attribute class

To be completely accurate, the compiler actually verifies that it could create the
attribute, and then stores the information to do so in the metadata. The compiler
does not create attribute instances at compile time.
Module 17 (Optional): Attributes 19

Example
To learn more about how the compiler handles attributes, consider the
following example:
[AttributeUsage(AttributeTargets.Class)]
public class DeveloperInfoAttribute: System.Attribute
{
...
}
.....
{
.....
}

[DeveloperInfo("Bert", Date="08-28-2001")]
public class MyClass
{
...
}

The Compilation Process

In the preceding example, when MyClass is compiled, the compiler will search
for an attribute class called DevloperInfoAttribute. If the class cannot be
located, the compiler will then search for DeveloperInfo.
After it finds DeveloperInfo, the compiler will check whether the attribute is
allowed on a class. Then it will check for a constructor that matches the
parameters specified in the attribute use. If it finds one, it creates an instance of
the object by calling the constructor with the specified values.
If there is a named parameter, the compiler matches the name of the parameter
with a field or property in the attribute class, and then sets the field or property
to the specified value. Then the current state of the attribute class is saved to the
metadata for the program element on which it is applied.

Note As is mentioned in the previous topic, it is a good practice to add the

suffix “Attribute” to the name of an attribute class. Strictly speaking, it is not
necessary to do so. Even if you omit the Attribute suffix as shown in the
example, your code will still compile correctly. However, without the Attribute
suffix there are potential issues concerning how the compiler searches for
classes. Always use the Attribute suffix.
20 Module 17 (Optional): Attributes

Using Multiple Attributes

Topic Objective
To describe how the same
attribute can be applied
multiple times to the same ! An Element Can Have More Than One Attribute
programming element.
# Define both attributes separately
Lead-in
Depending upon the ! An Element Can Have More Than One Instance of The
circumstances, it might be Same Attribute
useful to use a custom
attribute multiple times on # Use AllowMultiple = true
the same element.

*ILLEGAL FOR NON-TRAINER USE**

You can apply more than one attribute to a programming element, and you can
use multiple instances of the same attribute in an application.

Using Multiple Attributes

You can apply more than one attribute to a programming element. For example,
the following code shows how you can tag the FinancialComponent class with
two attributes: DeveloperInfo and DefaultProperty:
[DeveloperInfo("Bert", Date="08-28-2001")]
[DefaultProperty("Balance")]
public class FinancialComponent:
{
...
public long Balance
{
...
}
}
Module 17 (Optional): Attributes 21

Using the Same Attribute Multiple Times

The default behavior of a custom attribute does not permit multiple instances of
Delivery Tip the attribute. However, under some circumstances it might make sense to allow
Stress that the default
behavior of a custom
an attribute to be used on the same element more than once.
attribute is that it does not An example of this is the custom attribute DeveloperInfo. This attribute allows
permit its multiple use.
you to record the name of the developer that wrote a class. If more than one
developer was involved in the development, you need to use the DeveloperInfo
attribute more than once. For an attribute to permit this, you must mark it as
AllowMultiple in the AttributeUsage attribute, as follows:
[AttributeUsage(AttributeTargets.Class, AllowMultiple=true)]
public class DeveloperInfoAttribute: System.Attribute
{
...
}
22 Module 17 (Optional): Attributes

" Retrieving Attribute Values

Topic Objective
To introduce the topics
covered in this section.
! Examining Class Metadata
Lead-in
Having learned to create a ! Querying for Attribute Information
custom attribute and apply it
to a class, you now need to
be able to query and
process attribute
information.

*ILLEGAL FOR NON-TRAINER USE**

After you have applied attributes to programming elements in your code, it is
useful to be able to determine the values of the attributes. In this section, you
will learn how to use reflection to examine the attribute metadata of a class and
query classes for attribute information.
After completing this lesson, you will be able to:
! Use reflection to examine the attribute metadata of a class.
! Query classes for attribute information.
Module 17 (Optional): Attributes 23

Examining Class Metadata

Topic Objective
To describe how to access
the information inside a ! To Query Class Metadata Information:
class at run time.
Lead-in # Use the MemberInfo class in System.Reflection
Attribute information is # Populate a MemberInfo array by using the method
stored with the metadata of
a class. To gain access to it,
System.Type.GetMembers
you first need to retrieve the # Create a System.Type object by using the
metadata for that class.
typeof operator
! Example
System.Reflection.MemberInfo[
System.Reflection.MemberInfo[ ]] memberInfoArray;
memberInfoArray;
memberInfoArray
memberInfoArray == typeof(MyClass).GetMembers(
typeof(MyClass).GetMembers( );
);

*ILLEGAL FOR NON-TRAINER USE**

The .NET Framework runtime supplies a mechanism called reflection that
allows you to query information held in metadata. Metadata is where attribute
information is stored.

Using the MemberInfo Class

The .NET Framework provides a namespace named System.Reflection, which
contains classes that you can use for examining metadata. One particular class
in this namespace—the MemberInfo class—is very useful if you need to find
out about the attributes of a class.
To populate a MemberInfo array, you can use the GetMembers method of the
System.Type object. To create a System.Type object, you use the typeof
operator with a class or any other element, as shown in the following code:
System.Reflection.MemberInfo[ ] memberInfoArray;
memberInfoArray = typeof(MyClass).GetMembers( );
...

Once created, the memberInfoArray elements can be queried for metadata

information about the members of the class MyClass.

Tip If you need more detailed information, for example, if you want to
discover the values of attributes that a method has, you can use a MethodInfo
object. In addition, there are other “Info” classes: ConstructorInfo, EventInfo,
FieldInfo, ParameterInfo, and PropertyInfo. Detailed information about how
to use these classes is beyond the scope of this course. For more information,
search for “System.Reflection namespace” in the .NET Framework SDK.

Note MemberInfo is actually the abstract base class of the other “Info” types.
24 Module 17 (Optional): Attributes

Querying for Attribute Information

Topic Objective
To show how to use the ! To Retrieve Custom Attribute Information:
GetCustomAttributes
method. # Use GetCustomAttributes to retrieve all attribute
information as an array
Lead-in
Once you have the
MemberInfo for a class, you System.Reflection.MemberInfo
System.Reflection.MemberInfo typeInfo;
typeInfo;
can query to find out typeInfo
typeInfo == typeof(MyClass);
typeof(MyClass);
attribute information for that object[
object[ ]] attrs
attrs == typeInfo.GetCustomAttributes(false);
typeInfo.GetCustomAttributes(false);
class.

# Iterate through the array and examine the values of each

element in the array
# Use the IsDefined method to determine whether a
particular attribute has been defined for a class

*ILLEGAL FOR NON-TRAINER USE**

After you create a MemberInfo variable typeInfo and initialize it with
typeof(MyClass), you can query it to get information about the attributes that
are applied to its associated class.

Retrieving Attribute Information

The MemberInfo object has a method called GetCustomAttributes. This
method retrieves the information about all attributes of a class and stores it as
an array, as shown in the following code:
System.Reflection.MemberInfo typeInfo;
typeInfo = typeof(MyClass);
object [ ] attrs = typeInfo.GetCustomAttributes(false);

For Your Information You can then iterate through the array to find the values of the attributes that
GetCustomAttribute is an
overloaded method. The
you are interested in.
parameter specifies whether
to search the inheritance
chain.
Module 17 (Optional): Attributes 25

Iterating Through Attributes

You can iterate through the array of attributes and examine the value of each
one in turn. In the following code, the only attribute of interest is
DeveloperInfoAttribute, and all the others are ignored. For each
DeveloperInfoAttribute found, the values of the Developer and Date
properties are displayed as follows:
...
object [ ] attrs = typeInfo.GetCustomAttributes(false);
foreach(Attribute atr in attrs) {
if (atr is DeveloperInfoAttribute) {
DeveloperInfoAttribute dia = (DeveloperInfoAttribute)atr;
Console.WriteLine("{0} {1}", dia.Developer, dia.Date);
}
}
...

Tip GetCustomAttributes is an overloaded method. If you only want values

for that one attribute type, you can invoke this method by passing the type of
the custom attribute you are looking for through it, as shown in the following
code:
object [ ] attrs =
typeInfo.GetCustomAttributes(typeof(DeveloperInfoAttribute),
false);

Using the IsDefined Method

If there are no matching attributes for a class, GetCustomAttributes returns a
null object reference. However, to find out whether a particular attribute has
been defined for a class, you can use the IsDefined method of MemberInfo as
follows:
Type devInfoAttrType = typeof(DeveloperInfoAttribute);
if (typeInfo.IsDefined(devInfoAttrType, false)) {
Object [ ] attrs =
typeInfo.GetCustomAttributes(devInfoAttrType, false);
...
}

Note You can use the Microsoft Intermediate Language Disassembler to see
these attributes inside the assembly.
26 Module 17 (Optional): Attributes

Demonstration: Custom Attributes

Topic Objective
This demonstration shows
how to declare and apply
custom attributes and how
to use reflection to retrieve
custom attribute metadata.
Lead-in
This demonstration shows
how to declare and apply a
custom attribute and how to
use the .NET Framework
reflection mechanism to
retrieve this metadata
information.

*ILLEGAL FOR NON-TRAINER USE**

This demonstration shows how to declare a custom attribute and apply the
custom attribute to a class and to a method. The .NET Framework reflection
mechanism is then used to retrieve metadata information about the class and its
members including custom attributes. The code for this demonstration is
located in <install folder>\Democode\Mod17\CustomAttribute.
The demonstration declares a custom attribute MyAttribute and applies this
attribute both to a class named MyClass1 and to a public method of MyClass1
named MyMethod. The demonstration then uses reflection to iterate over and
print out metadata for MyClass1.
The output of this demonstration is similar to the following:
MyClass1 has 1 custom attributes
Custom Attribute MyAttribute's Name Property:
This is an example attribute associated with the class!
MyClass1

MyClass1 members:
member name: GetHashCode has 0 custom attributes:
member name: Equals has 0 custom attributes:
member name: ToString has 0 custom attributes:
member name: MyMethod has 1 custom attributes:
attribute has type: MyAttribute
Name Property: This is an example attribute associated!
with the method MyMethod in MyClass1
member name: GetType has 0 custom attributes:
member name: .ctor has 0 custom attributes:
Module 17 (Optional): Attributes 27

Lab 17: Defining and Using Attributes

Topic Objective
To introduce the lab.
Lead-in
In this lab, you will use the
predefined Conditional
attribute, and then create
and use a custom attribute.

*ILLEGAL FOR NON-TRAINER USE**

Explain the lab objectives.
Objectives
After completing this lab, you will be able to:
! Use the predefined Conditional attribute.
! Create a custom attribute.
! Add a custom attribute value to a class.
! Use reflection to query attribute values.

Prerequisites
Before working on this lab, you should be familiar with the following:
! Creating classes in C#
! Defining constructors and methods
! Using the typeof operator
! Using properties and indexers in C#

Estimated time to complete this lab: 45 minutes

28 Module 17 (Optional): Attributes

Exercise 1
Using the Conditional Attribute
In this exercise, you will use the predefined Conditional attribute to
conditionally execute your code.
Conditional execution is a useful technique if you want to incorporate testing or
debugging code into a project but do not want to edit the project and remove the
debugging code after the system is complete and functioning correctly.
During this exercise, you will add a method called DumpToScreen to the
BankAccount class. This method will display the details of the account. You
will use the Conditional attribute to execute this method depending on the
value of a symbol called DEBUG_ACCOUNT.

! Apply the Conditional attribute

1. Open the Bank.sln project in the install folder\Labs\Lab17\Starter\Bank
folder.
2. In the BankAccount class, add a public void method called
DumpToScreen that takes no parameters.
The method must display the contents of the account: account number,
account holder, account type, and account balance. The following code
shows a possible example of the method:
public void DumpToScreen( )
{
Console.WriteLine("Debugging account {0}. Holder is {1}.
!Type is {2}. Balance is {3}",
this.accNo, this.holder, this.accType, this.accBal);
}

3. Make use of the method’s dependence on the DEBUG_ACCOUNT

symbol.
Add the following Conditional attribute before the method as follows:
[Conditional("DEBUG_ACCOUNT")]

4. Add a using directive for the System.Diagnostics namespace.

5. Compile your code and correct any errors.
Module 17 (Optional): Attributes 29

! Test the Conditional attribute

1. Open the TestHarness.sln project in the install folder\Labs\Lab17\
Starter\TestHarness folder.
2. Add a reference to the Bank library.
a. In Solution Explorer, expand the TestHarness tree.
b. Right-click References, and then click Add Reference.
c. Click Browse, and then navigate to install folder\Labs\Lab17\
Starter\Bank\Bin\Debug.
d. Click Bank.dll, click Open, and then click OK.
3. Review the Main method of the CreateAccount class. Notice that it creates
a new bank account.
4. Add the following line of code to Main to call the DumpToScreen method
of myAccount:
myAccount.DumpToScreen( );

5. Save your work, compile the project, and correct any errors.
6. Run the test harness.
Notice that nothing happens. This is because the DumpToScreen method
has not been called.
7. Use the MSIL disassembler (ildasm), from the Visual Studio .NET
command prompt to examine install folder\Labs\Lab17\Starter\
Bank\Bin\Debug\Bank.dll.

Important To use Microsoft Visual Studio .NET tools within a command

prompt window, the command prompt window must have the proper
environment settings. The Visual Studio .NET Command Prompt window
provides such an environment. To run a Visual Studio .NET Command
Prompt window: on the start menu, point to All Programs, point to
Microsoft Visual Studio .NET, Visual Studio .NET Tools, and then click
Visual Studio .NET Command Prompt.

You will see that the DumpToScreen method is present in the

BankAccount class.
8. Double-click the DumpToScreen method to display the Microsoft
intermediate language (MSIL) code.
You will see the ConditionalAttribute at the beginning of the method. The
problem is in the test harness. Because of the ConditionalAttribute on
DumpToScreen, the runtime will effectively ignore calls made to that
method if the DEBUG_ACCOUNT symbol is not defined when the calling
program is compiled. The call is made, but because DEBUG_ACCOUNT
is not defined, the runtime finishes the call immediately.
30 Module 17 (Optional): Attributes

9. Close the MSIL disassembler.

10. Return to the test harness. At the top of the CreateAccount.cs file, before the
first using directive, add the following code:
#define DEBUG_ACCOUNT

This defines the DEBUG_ACCOUNT symbol.

11. Save and compile the test harness, correcting any errors.
12. Run the test harness.
Notice that the DumpToScreen method displays the information from
myAccount.
Module 17 (Optional): Attributes 31

Exercise 2
Defining and Using a Custom Attribute
In this exercise, you will create a custom attribute called
DeveloperInfoAttribute. This attribute will allow the name of the developer
and, optionally, the creation date of a class to be stored in the metadata of that
class. This attribute will permit multiple use because more than one developer
might be involved in the coding of a class.
You will then write a method that retrieves and displays all of the
DevloperInfoAttribute values for a class.

! Define a custom attribute class

1. Using Visual Studio .NET, create a new Microsoft Visual C# project, using
the information shown in the following table.
Element Value

Project Type Visual C# Projects

Template Class Library
Name CustomAttribute
Location install folder\Labs\Lab17\Starter

2. Change the name and file name of class Class1 to DeveloperInfoAttribute.

Make sure that you also change the name of the constructor.
3. Specify that the DeveloperInfoAttribute class is derived from
System.Attribute.
This attribute will be applicable to classes, enums, and structs only. It will
also be allowed to occur more than once when it is used.
4. Add the following AttributeUsage attribute before the class definition:
[AttributeUsage(AttributeTargets.Class |
!AttributeTargets.Enum | AttributeTargets.Struct,
!AllowMultiple=true)]

5. Document your attribute with a meaningful summary (between the

<summary> tags). Use the exercise description to help you.
6. The DeveloperInfoAttribute attribute requires the name of the developer of
the class as a mandatory parameter and takes the date that the class was
written as an optional string parameter. Add private instance variables to
hold this information, as follows:
private string developerName;
private string dateCreated;

7. Modify the constructor so that it takes a single string parameter that is also
called developerName, and add a line of code to the constructor that assigns
this parameter to this.developerName.
8. Add a public string read-only property called Developer that can be used to
get the value of developerName. Do not write a set accessor.
32 Module 17 (Optional): Attributes

9. Add another public string property that is called Date. This property should
have a get accessor that reads dateCreated and a set accessor that writes
dateCreated.
10. Compile the class and correct any errors.
Because the class is in a class library, the compilation process will produce
a DLL (CustomAttribute.dll) rather than a stand-alone executable program.
The complete code for the DeveloperInfoAttribute class follows:
namespace CustomAttribute
{
using System;
/// <summary>
/// This class is a custom attribute that allows
/// the name of the developer of a class to be stored
/// with the metadata of that class.
/// </summary>
[AttributeUsage(AttributeTargets.Class |
!AttributeTargets.Enum | AttributeTargets.Struct,
!AllowMultiple=true)]
public class DeveloperInfoAttribute: System.Attribute

{
private string developerName;
private string dateCreated;

// Constructor. Developer name is the only

// mandatory parameter for this attribute.
public DeveloperInfoAttribute(string developerName)
{
this.developerName = developerName;
}
public string Developer
{
get
{
return developerName;
}
}

// Optional parameter
public string Date
{
get
{
return dateCreated;
}
set
{
dateCreated = value;
}
}
}
}
Module 17 (Optional): Attributes 33

! Add a custom attribute to a class

1. You will now use the DeveloperInfo attribute to record the name of the
developer of the Rational number class. Open the Rational.sln project in
the install folder\Labs\Lab17\Starter\Rational folder.
2. Perform the following steps to add a reference to the CustomAttribute
library that you created earlier:
a. In Solution Explorer, expand the Rational tree.
b. Right-click References, and then click Add Reference.
c. In the Add Reference dialog box, click Browse.
d. Navigate to the install folder\Labs\Lab17\Starter\
CustomAttribute\Bin\Debug folder, and click CustomAttribute.dll.
e. Click Open, and then click OK.
3. Add a CustomAttribute.DeveloperInfo attribute to the Rational class,
specifying your name as the developer and the current date as the optional
date parameter, as follows:
[CustomAttribute.DeveloperInfo("Your Name",
!Date="Today")]

4. Add a second developer to the Rational class.

5. Compile the Rational project and correct any errors.
6. Open a Visual Studio .NET Command Prompt window and navigate to the
install folder\Labs\Lab17\Starter\Rational\Bin\Debug folder.
This folder should contain your Rational.exe executable.
7. Run the MSIL disassembler and open Rational.exe.
8. Expand the Rational namespace in the tree view.
9. Expand the Rational class.
10. Near the top of the class, notice your custom attribute and the values that
you supplied.
11. Close the MSIL disassembler.
34 Module 17 (Optional): Attributes

! Use reflection to query attribute values

Using the MSIL disassembler is only one way to examine attribute values.
You can also use reflection in C# programs. Return to Visual Studio, and
edit the TestRational class in the Rational project.
1. In the Main method, create a variable called attrInfo of type
System.Reflection.MemberInfo, as shown in the following code:
public static void Main( )
{
System.Reflection.MemberInfo attrInfo;
...

2. You can use a MemberInfo object to hold information about the members
of a class. Assign the Rational type to the MemberInfo object by using the
typeof operator, as follows:
attrInfo = typeof(Rational);

3. The attributes of a class are held as part of the class information. You can
retrieve the attribute values by using the GetCustomAttributes method.
Create an object array called attrs, and use the GetCustomAttributes
method of attrInfo to find all of the custom attributes used by the Rational
class, as shown in the following code:
object[ ] attrs = attrInfo.GetCustomAttributes(false);

4. Now you need to extract the attribute information that is stored in the attrs
array and print it. Create a variable called developerAttr of type
CustomAttribute.DeveloperInfoAttribute, and assign it the first element
in the attrs array, casting as appropriate, as shown in the following code:
CustomAttribute.DeveloperInfoAttribute developerAttr;
developerAttr =
!(CustomAttribute.DeveloperInfoAttribute)attrs[0];

Note In production code, you would use reflection rather than a cast to
determine the type of the attribute.

5. Use the get accessor of the DeveloperInfoAttribute attribute to retrieve the

Developer and Date attributes and print them out as follows:
Console.WriteLine("Developer: {0}\tDate: {1}",
!developerAttr.Developer, developerAttr.Date);

6. Repeat steps 4 and 5 for element 1 of the attrs array.

You can use a loop if you want to be able to retrieve the values of more than
two attributes.
Module 17 (Optional): Attributes 35

7. Compile the project and correct any errors.

The completed code for the Main method is shown in the following code:
namespace Rational
{
using System;

// Test harness
public class TestRational
{
public static void Main( )
{
System.Reflection.MemberInfo attrInfo;
attrInfo = typeof(Rational);
object[ ] attrs = attrInfo.GetCustomAttributes(false);
CustomAttribute.DeveloperInfoAttribute developerAttr;
developerAttr =
!(CustomAttribute.DeveloperInfoAttribute)attrs[0];
Console.WriteLine("Developer: {0}\tDate: {1}",
!developerAttr.Developer, developerAttr.Date);
developerAttr =
!(CustomAttribute.DeveloperInfoAttribute)attrs[1];
Console.WriteLine("Developer: {0}\tDate: {1}",
!developerAttr.Developer, developerAttr.Date);
}
}
}

Here is an alternative Main that uses a foreach loop:

public static void Main( )
{
System.Reflection.MemberInfo attrInfo;
attrInfo = typeof(Rational);
object[ ] attrs = attrInfo.GetCustomAttributes(false);

foreach (CustomAttribute.DeveloperInfoAttribute
! devAttr in attrs)
{
Console.WriteLine("Developer: {0}\tDate: {1}",
!devAttr.Developer, devAttr.Date);
}
}

8. When you run this program, it will display the names and dates that you
supplied as DeveloperInfoAttribute information to the Rational class.
36 Module 17 (Optional): Attributes

Review
Topic Objective
To reinforce module
objectives by reviewing
key points. ! Overview of Attributes
Lead-in ! Defining Custom Attributes
The review questions cover
some of the key concepts ! Retrieving Attribute Values
taught in the module.

*ILLEGAL FOR NON-TRAINER USE**

1. Can you tag individual objects by using attributes?
No. Attributes can be associated with classes or other types, or with
methods, parameters, return values, constructors, assemblies, delegates,
events, interfaces, properties, or fields, but not with individual objects.

2. Where are attribute values stored?

An attribute value is stored with the metadata of the programming
element that it was used with.

3. What mechanism is used to determine the value of an attribute at run time?

Reflection.
Module 17 (Optional): Attributes 37

4. Define an attribute class called CodeTestAttributes that is applicable only

to classes. It should have no positional parameters and two named
parameters called Reviewed and HasTestSuite. These parameters should be
of type bool and should be implemented by using read/write properties.
using System;
[AttributeUsage(AttributeTargets.Class)]
public class CodeTestAttributes: System.Attribute
{
public bool Reviewed
{
get { return reviewed; }
set { reviewed = value; }
}
public bool HasTestSuite
{
get { return hasTestSuite; }
set { hasTestSuite = value; }
}
private bool reviewed, hasTestSuite;
}

5. Define a class called Widget, and use CodeTestAttributes from the

previous question to mark that Widget has been reviewed but has no test
suite.
[CodeTestAttributes(Reviewed=true, HasTestSuite=false)]
class Widget
{
...
}

6. Suppose that Widget from the previous question had a method called
LogBug. Could CodeTestAttributes be used to mark only this method?
No. CodeTestAttributes can only target whole classes.
THIS PAGE INTENTIONALLY LEFT BLANK

070-298 MSPress - Designing and Managing A Windows Public Key Infrastructure (MOC 2821A) PDF
No ratings yet
070-298 MSPress - Designing and Managing A Windows Public Key Infrastructure (MOC 2821A) PDF
698 pages
Metastock Developer Kit
100% (1)
Metastock Developer Kit
152 pages
Developing Microsoft .NET Applications for Windows (Visual Basic .NET)
No ratings yet
Developing Microsoft .NET Applications for Windows (Visual Basic .NET)
710 pages
Developing Microsoft .NET Applications For Windows in Visual C# 2002
No ratings yet
Developing Microsoft .NET Applications For Windows in Visual C# 2002
710 pages
Visual Basic Scripting Edition & Windows Script Host Essentials PDF
No ratings yet
Visual Basic Scripting Edition & Windows Script Host Essentials PDF
394 pages
CSharp - Introduction To C# Programming For The Microsoft - Net Platform Pre Release)
100% (3)
CSharp - Introduction To C# Programming For The Microsoft - Net Platform Pre Release)
12 pages
Building CRM Desktop Applica-Tion Using Java 8 PDF
No ratings yet
Building CRM Desktop Applica-Tion Using Java 8 PDF
86 pages
Microsoft MSDN Training - MOC 2095 Implementing Microsoft SharePoint Portal
No ratings yet
Microsoft MSDN Training - MOC 2095 Implementing Microsoft SharePoint Portal
522 pages
Inside AX 2012 R3
60% (5)
Inside AX 2012 R3
86 pages
Ide
No ratings yet
Ide
468 pages
ITAM-1300 Lab - Mannual - 23.10.3
No ratings yet
ITAM-1300 Lab - Mannual - 23.10.3
109 pages
Wonderware Application Server User's Guide: Invensys Systems, Inc
No ratings yet
Wonderware Application Server User's Guide: Invensys Systems, Inc
322 pages
PHP - PG
No ratings yet
PHP - PG
55 pages
Application Techniques
No ratings yet
Application Techniques
712 pages
Wonderware Application Server User's Guide: Invensys Systems, Inc
No ratings yet
Wonderware Application Server User's Guide: Invensys Systems, Inc
262 pages
Model Sim Tutorial
No ratings yet
Model Sim Tutorial
88 pages
DC CGD en
No ratings yet
DC CGD en
318 pages
978 1 63057 050 7 - Toc PDF
No ratings yet
978 1 63057 050 7 - Toc PDF
10 pages
PB 12.5 Application Techniques
No ratings yet
PB 12.5 Application Techniques
716 pages
Ug871 Vivado High Level Synthesis Tutorial
No ratings yet
Ug871 Vivado High Level Synthesis Tutorial
271 pages
Customizing and Administration Guide OpenText DocuLink For SAP Solutions (DC160208-CGD-En-01)
No ratings yet
Customizing and Administration Guide OpenText DocuLink For SAP Solutions (DC160208-CGD-En-01)
408 pages
Filenet
No ratings yet
Filenet
411 pages
NetSim User Manual
No ratings yet
NetSim User Manual
464 pages
Csts 250 CB
No ratings yet
Csts 250 CB
110 pages
NetSim User Manual
No ratings yet
NetSim User Manual
244 pages
Opinnaytetyo Aedma Martin
No ratings yet
Opinnaytetyo Aedma Martin
51 pages
PB Application Techniques
No ratings yet
PB Application Techniques
784 pages
PetaLinux_UG1144_2024-1
No ratings yet
PetaLinux_UG1144_2024-1
299 pages
Pro E 2
No ratings yet
Pro E 2
501 pages
Data Structuresss
No ratings yet
Data Structuresss
674 pages
Complete Tutorial
No ratings yet
Complete Tutorial
149 pages
EMC Documentum Business Process Suite: Best Practices Guide P/N 300-009-005 A01
No ratings yet
EMC Documentum Business Process Suite: Best Practices Guide P/N 300-009-005 A01
118 pages
MICROSOFT .NET REMOTING
No ratings yet
MICROSOFT .NET REMOTING
238 pages
NFV Performance
No ratings yet
NFV Performance
49 pages
Case Study of Pattern Application Dedication
No ratings yet
Case Study of Pattern Application Dedication
68 pages
jb283 1.0 Student Guide
No ratings yet
jb283 1.0 Student Guide
414 pages
bm_cimplicity_project_setup_master
No ratings yet
bm_cimplicity_project_setup_master
435 pages
Content Manager
No ratings yet
Content Manager
496 pages
Customizing and Administration Guide OpenText DocuLink For SAP Solutions (DC100500-CGD-En)
No ratings yet
Customizing and Administration Guide OpenText DocuLink For SAP Solutions (DC100500-CGD-En)
412 pages
sg246699 New
No ratings yet
sg246699 New
274 pages
Power Builder 8 Getting Started
100% (5)
Power Builder 8 Getting Started
304 pages
Manual Completo Winsql
No ratings yet
Manual Completo Winsql
223 pages
A Refresher Course in MATLAB: Institute of Sound and Vibration Research
No ratings yet
A Refresher Course in MATLAB: Institute of Sound and Vibration Research
60 pages
Ug895 Vivado System Level Design Entry
No ratings yet
Ug895 Vivado System Level Design Entry
129 pages
6RMC CodeWatch UG
No ratings yet
6RMC CodeWatch UG
152 pages
Archestra IDE
100% (3)
Archestra IDE
468 pages
Plain JavaScript: Learning the Front-End
From Everand
Plain JavaScript: Learning the Front-End
Roger Beans-Rivet
No ratings yet
Programming the Photon: Getting Started with the Internet of Things
From Everand
Programming the Photon: Getting Started with the Internet of Things
Christopher Rush
5/5 (1)
Business Object Modeling (BOM) workbook: A pattern-based approach to creating, managing and using an enterprise data model
From Everand
Business Object Modeling (BOM) workbook: A pattern-based approach to creating, managing and using an enterprise data model
Martine Alaerts
No ratings yet
Basic Research and Technologies for Two-Stage-to-Orbit Vehicles: Final Report of the Collaborative Research Centres 253, 255 and 259
From Everand
Basic Research and Technologies for Two-Stage-to-Orbit Vehicles: Final Report of the Collaborative Research Centres 253, 255 and 259
Dieter Jacob
No ratings yet
Microsoft SQL Server 2005: A Beginner''s Guide
From Everand
Microsoft SQL Server 2005: A Beginner''s Guide
Dusan Petkovic
No ratings yet
Open Innovation and Business Success
From Everand
Open Innovation and Business Success
Monika Gawarzynska
No ratings yet
Content Creation Revolution with chatGPT
From Everand
Content Creation Revolution with chatGPT
Maria Cowen
No ratings yet
Programming the Intel Galileo: Getting Started with the Arduino -Compatible Development Board
From Everand
Programming the Intel Galileo: Getting Started with the Arduino -Compatible Development Board
Christopher Rush
5/5 (1)
ChatGPT for Business: Strategies for Success
From Everand
ChatGPT for Business: Strategies for Success
Matthew C. Smith
1/5 (1)
The TAB Book of Arduino Projects: 36 Things to Make with Shields and Proto Shields
From Everand
The TAB Book of Arduino Projects: 36 Things to Make with Shields and Proto Shields
Simon Monk
5/5 (7)
Blog Smarter, Not Harder: SEO, Blogging, and AI Strategies to Skyrocket Your Traffic
From Everand
Blog Smarter, Not Harder: SEO, Blogging, and AI Strategies to Skyrocket Your Traffic
Jay Nans
No ratings yet
Benefits of semantic data models. A study in the European goods transport industry
From Everand
Benefits of semantic data models. A study in the European goods transport industry
Andreas A. Pelekies
No ratings yet
Programming Arduino: Getting Started with Sketches, Third Edition
From Everand
Programming Arduino: Getting Started with Sketches, Third Edition
Simon Monk
No ratings yet
Developing Intelligent Agent Systems: A Practical Guide
From Everand
Developing Intelligent Agent Systems: A Practical Guide
Lin Padgham
3/5 (1)
An Analysis of Siemens AG’s Quality Management System
No ratings yet
An Analysis of Siemens AG’s Quality Management System
8 pages
TP-LSMULTI-SDK-64 Release Notes
No ratings yet
TP-LSMULTI-SDK-64 Release Notes
2 pages
PhonePe Statement Oct2024 Nov2024
No ratings yet
PhonePe Statement Oct2024 Nov2024
3 pages
Datasheet
No ratings yet
Datasheet
58 pages
HFDG
No ratings yet
HFDG
1,007 pages
Defect Management V1
No ratings yet
Defect Management V1
4 pages
Star Bright Satellite Radio Date Posted
No ratings yet
Star Bright Satellite Radio Date Posted
1 page
Generate Keystore and Certificate For SAP BO BI4.0 PDF
No ratings yet
Generate Keystore and Certificate For SAP BO BI4.0 PDF
2 pages
Communication Skills and Office Automation
No ratings yet
Communication Skills and Office Automation
19 pages
Brother MFC9440CN Parts Manual
100% (1)
Brother MFC9440CN Parts Manual
43 pages
Saf T Gard Actuators
No ratings yet
Saf T Gard Actuators
14 pages
Concept Paper1
No ratings yet
Concept Paper1
38 pages
A4 Assessment Specifications (2024 S1)
No ratings yet
A4 Assessment Specifications (2024 S1)
8 pages
Source Data For QM - Selected Set Code
No ratings yet
Source Data For QM - Selected Set Code
6 pages
User Manual OHAUS RANGER 4000
No ratings yet
User Manual OHAUS RANGER 4000
41 pages
CENTRALA TELEFONICA OpenScape 4000 Systems Components (143-274)
No ratings yet
CENTRALA TELEFONICA OpenScape 4000 Systems Components (143-274)
132 pages
Arm Course
No ratings yet
Arm Course
2 pages
Data Loss Prevention
No ratings yet
Data Loss Prevention
20 pages
WSS M99P9999 A1
No ratings yet
WSS M99P9999 A1
39 pages
1990 Volkswagen VW Vanagon - Transporter Instruction Manual - Owners Handbook ... (PDFDrive)
No ratings yet
1990 Volkswagen VW Vanagon - Transporter Instruction Manual - Owners Handbook ... (PDFDrive)
165 pages
AIR PORT Project
No ratings yet
AIR PORT Project
16 pages
240-158191826 Generation Operation Training Requirements Specification For Power Plant Simulator
No ratings yet
240-158191826 Generation Operation Training Requirements Specification For Power Plant Simulator
27 pages
PIP-MS 1-5K Manual (ESP) - Inversor
No ratings yet
PIP-MS 1-5K Manual (ESP) - Inversor
40 pages
AIS Mobile Application User Guide - v1.3.0
No ratings yet
AIS Mobile Application User Guide - v1.3.0
47 pages
Rosco ChipSpreader SPR-H Manual
No ratings yet
Rosco ChipSpreader SPR-H Manual
256 pages
Outback 2009 2.5, 2,5t 3.0
No ratings yet
Outback 2009 2.5, 2,5t 3.0
5,102 pages
What Is Printed Learning Material
No ratings yet
What Is Printed Learning Material
2 pages
Data Mining 20
No ratings yet
Data Mining 20
7 pages
Amd 96960
No ratings yet
Amd 96960
110 pages
Master The PRINCE2 Themes With Pictures
100% (1)
Master The PRINCE2 Themes With Pictures
11 pages