ASP.NET.in.a.Nutshell.Second.Edition [Electronic resources] نسخه متنی

21.1 Reading a Quick-Reference Entry

Each quick-reference entry contains quite a bit of information. The
sections that follow describe the structure of a quick-reference
entry, explaining what information is available, where it is found,
and what it means. While reading the descriptions that follow, you
will find it helpful to flip through the reference section itself to
find examples of the described features.

21.1.1 Type Name, Namespace, Assembly, Type Category, and Flags

Each quick-reference entry begins with a four-part title that
specifies the name, namespace (followed by the assembly in
parentheses), and type category of the type, and may also specify
various additional flags that describe the type. The type name
appears in bold at the upper-left side of the title. The namespace
and assembly appear in smaller print in the lower-left side, below
the type name.

The upper-right portion of the title indicates the type category of
the type (class, delegate, enum, interface, or struct). The
"class" category may include
modifiers such as sealed or
abstract.

In the lower-right corner of the title, you may find a list of flags
that describe the type. The possible flags and their meanings are as
follows:

ECMA

Specifies that the type is part of the ECMA CLI specification.

serializable

Specifies that the type, or a base class, implements
System.Runtime.Serialization.ISerializable or has been flagged with
the System.Serializable attribute.

marshal by reference

This class, or a superclass, derives from System.MarshalByRefObject.

context bound

This class, or a superclass, derives from System.ContextBoundObject.

disposable

Specifies that the type implements the System.IDisposable interface.

flag

Specifies that the enumeration be marked with the
System.FlagsAttribute attribute.

21.1.2 Description

The title of each quick-reference entry is followed by a short
description of the most important features of the type. This
description may be anywhere from a couple of sentences to several
paragraphs long.

21.1.3 Synopsis

The most important part of every quick-reference entry is the
synopsis, which follows the title and description. The synopsis for a
type looks much like its source code, except that the member bodies
are omitted and some additional annotations are added. If you know C#
syntax, you know how to read the type synopsis.

The first line of the synopsis contains information about the type
itself. It begins with a list of type modifiers, such as
abstract and sealed. These
modifiers are followed by the class,
delegate, enum,
interface, or struct keyword
and then by the name of the type. The type name may be followed by a
colon (:) and a base class or interfaces that the type implements.

The type definition line is followed by a list of the members that
the type defines. This list includes only members that are explicitly
declared in the type, are overridden from a base class, or are
implementations of an interface member. Members that are simply
inherited from a base class are not shown; you will need to look up
the base class definition to find those members.

Once again, if you understand basic C# syntax, you should have no
trouble making sense of these lines. The listing for each member
includes the modifiers, type, and name of the member. For methods,
the synopsis also includes the type and name of each method
parameter. The member names are in boldface, so it is easy to scan
the list of members looking for the one you want. The names of method
parameters are in italics to indicate that they should not be used
literally. The member listings are printed on alternating gray and
white backgrounds to keep them visually separate.

21.1.3.1 Member availability and flags

Each member listing is a single line that defines the syntax for that
member. These listings use C# syntax, so their meaning is immediately
clear to any C# programmer. Some auxiliary information associated
with each member synopsis, however, requires explanation.

The area to the right of the member synopsis displays a variety of
flags that provide additional information about the member. Some
flags indicate additional specification details that do not appear in
the member syntax itself.

The following flags may be displayed to the right of a member
synopsis:

overrides

Indicates that a method overrides a method in one of its base
classes. The flag is followed by the name of the base class that the
method overrides.

implements

Indicates that a method implements a method in an interface. The flag
is followed by the name of the implemented interface.

=

For enumeration fields and constant fields, this flag is followed by
the constant value of the field. Only constants of primitive and
String types and constants with the value null are
displayed. Some constant values are specification details, while
others are implementation details. Some constants, such as
System.BitConverter.IsLittleEndian, are platform dependent.
Platform-dependent values shown in this book conform to the
System.PlatformID.Win32NT platform (32-bit Windows NT, 2000, or XP).
The reason why symbolic constants are defined, however, is so you can
write code that does not rely directly upon the constant value. Use
this flag to help you understand the type, but do not rely upon the
constant values in your own programs.

21.1.3.2 Functional grouping of members

Within a type synopsis, the members are not listed in strict
alphabetical order. Instead, they are broken down into functional
groups and listed alphabetically within each group. Constructors,
events, fields, methods, and properties are all listed separately.
Instance methods are kept separate from shared (class) methods.
Public members are listed separately from protected members. Grouping
members by category breaks a type down into smaller, more
comprehensible segments, making the type easier to understand. This
grouping also makes it easier for you to find a desired member.

Functional groups are separated from one another in a type synopsis
with comments, such as:

Public Constructors

or:

// Protected Instance Properties

or:

// Events

The various functional categories follow below (in the order in which
they appear in a type synopsis):

Constructors

Displays the constructors for the type. Public and protected
constructors are displayed separately in subgroupings. If a type
defines no constructor at all, the compiler adds a default
parameterless constructor that is displayed here. If a type defines
only private constructors, it cannot be instantiated, so no
constructor appears. Constructors are listed first because the first
thing you do with most types is instantiate them by calling a
constructor.

Fields

Displays all fields defined by the type, including constants. Public
and protected fields are displayed in separate subgroups. Fields are
listed here, near the top of the synopsis, because constant values
are often used throughout the type as legal values for method
parameters and return values.

Properties

Lists all the properties of the type, breaking them down into
subgroups for public and protected shared properties and public and
protected instance properties. After the property name, its accessors
(get or set) are shown.

Static methods

Lists the static methods (class methods) of the type, broken down
into subgroups for public shared methods and protected shared
methods.

Public instance methods

Contains all public instance methods.

Protected instance methods

Contains all protected instance methods.

21.1.4 Class Hierarchy

For any type that has a nontrivial inheritance hierarchy, the synopsis is
followed by a "Hierarchy" section.
This section lists all of the base classes of the type, as well as
any interfaces implemented by those base classes. It also lists any
interfaces implemented by an interface. In the hierarchy listing,
arrows indicate base class to derived class relationships, while the
interfaces implemented by a type follow the type name in parentheses.
For example, the following hierarchy indicates that System.IO.Stream
implements IDisposable and extends MarshalByRefObject, which itself
extends Object:

System.Object  System.MarshalByRefObject  System.IO.Stream(System.IDisposable)

If a type has subtypes, the
"Hierarchy" section is followed by
a "Subtypes" section that lists
those subtypes. If an interface has implementations, the
"Hierarchy" section is followed by
an "Implementations" section that
lists those implementations. While the
"Hierarchy" section shows ancestors
of the type, the "Subtypes" or
"Implementations" section shows
descendants.

21.1.5 Cross References

The hierarchy section of a quick-reference entry is followed by
optional cross-reference sections that indicate other related types
and methods that may be of interest. These sections include:

Passed to

This section lists all members (from other types) that are passed an
object of this type as an argument, including properties whose values
can be set to this type. It is useful when you have an object of a
given type and want to know where it can be used.

Returned by

This section lists all members that return an object of this type,
including properties whose values can take on this type. It is useful
when you know that you want to work with an object of this type, but
don't know how to obtain one.

Valid on

For attributes, this section lists the attribute targets that the
attribute can be applied to.

Associated events

For delegates, this section lists the events it can handle.

21.1.6 A Note About Type Names

Throughout the quick reference, you'll notice that
types are sometimes referred to by type name alone, and at other
times are referred to by type name and namespace. If namespaces were
always used, the type synopses would become long and hard to read. On
the other hand, if namespaces were never used, it would sometimes be
difficult to know what type was being referred to. The rules for
including or omitting the namespace name are complex. However, they
can be summarized as follows:

• If the type name alone is ambiguous, the namespace name is always
  used.

• If the type is part of the System namespace or is a commonly used
  type like System.Collection.ICollection, the namespace is omitted.

• If the type being referred to is part of the current namespace (and
  has a quick-reference entry in the current chapter), the namespace is
  omitted. The namespace is also omitted if the type being referred to
  is part of a namespace that contains the current namespace.