This book is intended for anyone building applications using the .NET Framework. It is meant to be a dictionary-style reference to the core types in the Framework.
The .NET Framework is huge. The amount of time that would be required limits our ability to cover the entire .NET Framework in the depth it deserves. As a result, we have focused the scope of this book on the most important, widely used types in the Framework. Luckily, such a subset was already created in the standardization process of the Common Language Runtime and the C# Programming Language. This book covers the second half of that subset (Volume 1 covered the first half). In the printed portion of this volume you will find all the type-level information for these types. Both the type-level information and member-level information are available in electronic form on the CD.
To make the standard more accessible, this book includes the following features:
- Annotations from key folks involved in the design of the .NET Framework
- Namespace overviews
- Type descriptions
- Sample code to illustrate type uses
- A fully searchable CD that includes all source code, descriptions, annotations, and examples
These features not only bring the standard to life, but more importantly, they serve as a convenient, informative reference to the most used types in the .NET Framework.
At the Professional Developers Conference in October 2001, Microsoft, in partnership with HP and Intel, began the ECMA standardization process of three core parts of its new developer platform: the Common Language Infrastructure (CLI), the C# programming language, and a subset of the .NET Framework that is included in the CLI and referenced in the C# specification.
The CLI and the C# programming language are covered in other books in this series. Jim Miller and Susann Ragsdales The Common Language Infrastructure Annotated Standard (Addison-Wesley, 2004) covers the CLI, which includes the metadata file format, IL Instruction set, and the type system. The C# Programming Language (Addison-Wesley, 2004) by Anders Hejlsberg, Scott Wiltamuth, and Peter Golde covers the C# programming language specification.
This book covers the second half of the .NET Framework as standardized in ECMA 335 and ISO 23271. The standards break the .NET Framework into seven different libraries to allow conformant implementations in resource-constrained environments. Those libraries are as follows:
Base Class LibraryA simple runtime library for modern programming languages. It serves as the standard for the runtime library for the language C#, as well as one of the CLI standard libraries. It provides types to represent the built-in data types of the CLI, simple file access, custom attributes, security attributes, string manipulation, formatting, streams, collections, and so forth.
Extended Numerics LibraryProvides the support for floating-point (System.Single, System.Double) and extended-precision (System.Decimal) data types. Like the Base Class Library, this library is directly referenced by the C# standard.
Network LibraryProvides simple networking services, including direct access to network ports and HTTP support.
Reflection LibraryProvides the ability to examine the structure of types, create instances of types, and invoke methods on types, all based on a description of the type.
XML LibraryProvides a simple pull-style parser for XML. It is designed for resource-constrained devices, yet provides a simple user model.
Runtime Infrastructure LibraryProvides the services needed by a compiler to target the CLI and the facilities needed to dynamically load types from a stream in the file format specified. For example, it provides System.BadImageFormatException, which is thrown when a stream that does not have the correct format is loaded.
Extended Array LibraryProvides support for non-vector arrays, that is, arrays that have more than one dimension and arrays that have non-zero lower bounds.
The first volume of the .NET Framework Standard Library Reference covered the Base Class Library, the Extended Numerics Library and the Extended Array Library. This volume will contain the remaining libraries, as well as Microsoft-specific members on those types.
To facilitate reader understanding, for each namespace we cover we provide an overview that describes the functionality and the inheritance hierarchy of types defined in that namespace. At the end of the namespace overview section we include a complete inheritance hierarchy for all the types covered in this volume. In the diagrams we differentiate the various kinds of types that make up the framework.
Types are described in their own chapters, which are organized alphabetically by type name.
The header contains the namespace name, the type name, and the library name from the ECMA\ISO Standard.
Under the header we include a diagram representing the full inheritance hierarchy for this type, subclasses of this type found in this volume, and any interfaces they implement. The type being described is shown with a gray background .
This section contains the C# declaration syntax for all members defined on this type. It is meant to provide a quick reference in a very familiar format to what is in the type. In this summary we highlight certain attributes of these members.
CF Indicates the member is not available in the .NET Compact Framework. If not included the member is available.
MS Indicates that the member is not included in the ECMA\ISO standard.
1.1 Indicates that the member is new in V1.1 of the .NET Framework.
This section contains a detailed description of how this type is to be used. For the most part this text is taken directly from the standard.
Throughout this section we provide annotations from key members of the design team at Microsoft and members of the ECMA standardization committee. The comments in this section vary widely, and include notes on everything from common issues to the history of the class design or standardization process to areas where, in retrospect, the designers feel they could have done better.
Heres an example of an annotation from Brad Abrams on the AppDomain class. Each annotation is attributed to individuals by their initials.
We introduced Application Domains as a lightweight process mechanism. Because managed code can be verifiably type safe (memory safe) we did not need the heavyweight address space barrier that processes provide. This savings works out well most of the time. However, when using interop with unmanaged code it does cause some problems when type safety is violated. One notable example of this is the loader-lock and AppDomain marshaling problem that C++ was succeptible to. We fixed this problem in a service pack of v1.1.
In this section we provide sample code illustrating use of the type. Some samples are from the standard, but we added many more to facilitate a deeper and quicker understanding of the use of the type. All the samples we provide are fully compilable programs and include selected output .
All of these samples have been tested with V1.0 and V1.1 of the .NET Framework and the appropriate ones have been tested on the .NET Compact Framework.
Complete source code for the samples is available on the CD that is included in the back of the book.
The detailed descriptions of the members are included in the electronic version of the book on the CD. To facilitate easy look-ups, the member descriptions appear in the same order as the type summary sections. Each member contains some or all of the following fields:
SyntaxC# declaration syntax is provided for familiar reference. ILASM syntax is provided for completeness.
SummaryShort description of the members purpose.
ParametersTable of parameters accepted by this member and their meaning.
DescriptionA complete description of this member.
Return ValueThe value and range returned by this method.
Property ValueThe value of this property.
ExceptionsTable of the common exceptions thrown by this member.
PermissionsTable of the code access permissions demanded by this method.
ExampleAn example using this member following the same pattern as the type samples.
Conventions Used in This Book
Courier is used for all source code blocks, including syntax declarations, class names, and member names.
In order to aid readability, the namespace portion of the fully qualified type names were removed when the result was unambigous. The following guidelines were used:
- When referring to a member of the type being addressed, only the member names were used.
- When referring to a type, other than the one being addressed, but in the same namespace, only the type name is used.
In addition to including the content from the ISO CLI standard, this book includes a number of other features:
- For every type covered in the book we include all the members as defined in V1.1 of the .NET Framework. Many members were left out of the ECMA standard to streamline platform work because types in the signature were not in the standard or because of scheduling reasons. As this book is primarily targeted at developers using the .NET Framework, we elected to include all the members of the types we cover, not just those that are standardized.
- Nearly every type contains annotations from key members of the design team at Microsoft and members of the ECMA standards group. These annotations bring rationale, history, and other interesting notes about the types covered.
- We added more than 1,000 samples to the book. Nearly every member has a working sample with output included. All of the samples can be found on the CD.
Many people contributed to making this book possible. We would like to thank:
- Martin Heller, series editor, for his technical guidance as well as coordinating a myriad of details involved in creating the book.
- Joan Murray from Addison-Wesley for her patience and guidance.
- David Platt for producing the excellent namespace overviews provided here.
- Joel Marcey for providing technical support in working with the Xml doc format used in the ECMA standard and for providing thoughtful and lighthearted annotations.
- The contributing members of ECMA TC-39 TG1 and TG2 for formalizing the CLI and C# Standards on which this book is based.
- Mike Koenig, my manager here at Microsoft, for allowing me the time to contribute this work.
- Alex Homer, Kevin Westhead, and Joel Marcey for sharing their coding expertise through the large set of samples shown in this book.
- The many .NET developers who reviewed early versions of the manuscript and provided valuable feedback, including William Bartholomew, Alfred Gary Myers, Jr., Jordan Matthiesen, Kevin Westhead, and Bill Wagner.
Lead Program Manager, .NET Framework Team