Pro Visual C++-CLI And The .NET 2.0 Platform (2006) [eng]-1

208 C H A P T E R 5 ■ T H E . N E T F R A M E W O R K C L A S S L I B R A R Y

Table 5-12. Common System::Resources Namespace Classes

Class Name	Description
ResourceManager	Provides the ability to access culture-specific resources from an assembly
	or satellite assembly. It can also read from a specified resource file or stream.
ResourceReader	Provides the ability to read from a specified resource file or stream.
ResourceWriter	Provides the ability to write to a specified resource file or stream.

System::Runtime::InteropServices

The System::Runtime::InteropServices namespace provides a wide variety of members that support COM interoperability and platform invoke services.

.NET has not exposed the entire Win32. But all is not lost, because the

System::Runtime::InteropServices namespace provides the DLLImportAttribute and some helper attributes to call into these APIs or any other C DLL API.

Developers have made a huge investment in developing COM objects, and it would be quite a waste of effort to rewrite the objects into .NET object. Because of this, the System::Runtime::InteropServices namespace was created to provide types to make interfacing with COM objects extremely easy.

Interfacing with C DLLs and COM objects is explored in more detail with advanced unsafe programming in Chapter 21. Table 5-13 shows some of the more common classes that you might use within the System::Runtime::InteropServices namespace.

To access System::Runtime::InteropServices, you need to reference the mscorlib.dll assembly:

#using <mscorlib.dll>

Table 5-13. Common System::Runtime::InteropServices Namespace Classes

Class Name	Description
ClassInterfaceAttribute	Used to indicate the type of interface that will be generated
	for the public member types exposed by a managed type
	to a COM
ComDefaultInterfaceAttribute	Used to specify a default interface exposed to the COM
ComRegisterFunctionAttribute	Used to specify the custom method to call when you
	register an assembly for use with the COM
ComSourceInterfacesAttribute	Used to identify a list of interfaces that are exposed as
	COM event sources for the class
ComUnregisterFunctionAttribute	Used to specify the custom method to call when you
	unregister an assembly for use with the COM
DispIdAttribute	Used to specify the COM dispatch identifier (DISPID) of a
	method, field, or property

C H A P T E R 5 ■ T H E . N E T F R A M E W O R K C L A S S L I B R A R Y

209

Table 5-13. Common System::Runtime::InteropServices Namespace Classes

Class Name	Description
DllImportAttribute	Used to indicate that the method is exposed by an
	unmanaged dynamic-link library (C DLL) as a static entry
	point and thus can be called by the platform invoke
	services (PInvoke)
GuidAttribute	Used to supply an explicit System::Guid to a class interface
	or type library when an automatic GUID is undesirable
IDispatchImplAttribute	Used to indicate which IDispatch implementation the
	CLR uses when exposing dual interfaces and dispinterfaces
	to COM
InAttribute	Used to indicate that data should be marshaled only from
	the caller to the callee
InterfaceTypeAttribute	Used to indicate how a managed interface is exposed to
	COM (dual, dispatch-only, or IUnknown)
Marshal	A collection of methods for allocating unmanaged memory,
	copying unmanaged memory, and converting managed to
	unmanaged types, as well as an assortment of methods
	for interacting with unmanaged code
OutAttribute	Indicates that data should be marshaled only from the
	callee back to the caller
ProgIdAttribute	An attribute that allows the assigning of a ProgID to a class
RegistrationServices	A collection of services for registering and unregistering
	managed assemblies for use from COM

System::Runtime::Remoting

System::Runtime::Remoting is a hierarchy of namespaces providing classes and interfaces that allow developers the ability to create and configure distributed applications. For those of you who are pre-

.NET developers, this namespace hierarchy replaces (or is possibly equivalent to) DCOM.

A distributed application is an application where its parts are distributed among multiple machines allowing improved performance, scalability, and maintainability. Development using System::Runtime::Remoting hierarchy of namespaces is a large topic and well beyond the scope of this book. Fortunately, Advanced .NET Remoting, Second Edition by Ingo Rammer (Apress, 2005) covers in depth how to develop applications using this namespace hierarchy. Although the book is written for C# developers, I think you can still use it to get the information you need.

To access System::Runtime::Remoting, you need to reference the mscorlib.dll assembly:

#using <mscorlib.dll>

Table 5-14 provides a list of all the namespaces that make up the System::Runtime::Remoting hierarchy.

210 C H A P T E R 5 ■ T H E . N E T F R A M E W O R K C L A S S L I B R A R Y

Table 5-14. System::Runtime::Remoting Hierarchy Namespaces

Namespace	Description
System::Runtime::Remoting	Provides classes and interfaces that allow devel-
	opers to create and configure distributed
	applications. Some of the more important classes
	of the namespace are RemotingConfiguration,
	RemotingServices, and ObjRef.
System::Runtime::Remoting::Activation	Provides classes that support server and client
	activation of remote objects.
System::Runtime::Remoting::Channels	Provides classes that support and handle
	channels (objects that transport messages
	between applications across remoting
	boundaries) and channel sinks.
System::Runtime::Remoting::Channels::Http	Provides classes that support and handle chan-
	nels and channel sinks using the HTTP protocol.
System::Runtime::Remoting::Channels::Ipc	Provides classes that support and handle
	channels and channel sinks using the IPC
	protocol.
System::Runtime::Remoting::Channels::Tcp	Provides classes that support and handle
	channels and channel sinks using the TCP
	protocol.
System::Runtime::Remoting::Contexts	Provides classes that define the contexts
	(ordered sequence of properties that defines
	an environment for the class) for all objects
	that reside within.
System::Runtime::Remoting::Lifetime	Provides classes that manage the lifetime of
	remote objects.
System::Runtime::Remoting::Messaging	Provides classes that are used to create and
	transmit messages.
System::Runtime::Remoting::Metadata	Provides classes and attributes that can be used
	to customize generation and processing of
	SOAP for objects and fields.
System::Runtime::Remoting::Metadata::W3cXsd2001	Provides classes that contains the XML Schema
	Definition (XSD) defined by the World Wide
	Web Consortium (W3C) in 2001.
System::Runtime::Remoting::MetadataServices	Provides classes that contain the classes used to
	convert metadata to and from XML schema for
	the remoting infrastructure.
System::Runtime::Remoting::Proxies	Provides classes that control and provide func-
	tionality for proxies.
System::Runtime::Remoting::Services	Provides classes that contain service classes that
	provide functionality to the .NET Framework.

C H A P T E R 5 ■ T H E . N E T F R A M E W O R K C L A S S L I B R A R Y

211

System::Runtime::Serialization

System::Runtime::Serialization contains all the classes used to serialize and deserialize objects. Serialization is the process of converting an object, most likely an instance of a class to a linear sequence of bytes appropriate for things like storage or transmission over a stream. Deserialization is the conversion of a linear sequence of bytes back into an object.

The .NET Framework provides two formats for the linear sequence: SOAP and binary. You can also create your own format as well. The choice of which format is determined by which formatter namespace is chosen.

I cover serialization and deserialization of class objects in Chapter 8. Table 5-15 shows some of the common classes that you might use within the System::Runtime::Serialization namespace.

To access System::Runtime::Serialization, you need to reference the mscorlib.dll assembly:

#using <mscorlib.dll>

Table 5-15. Common System::Runtime::Serialization Namespace Classes

Class Name	Description
Formatter	The base functionality for the CLR serialization
	formatters
Formatters::Binary::BinaryFormatter	A class used to serialize and deserialize objects into
	a binary format
Formatters::Soap::SoapFormatter	A class used to serialize and deserialize objects into
	a SOAP format
FormatterServices	A class containing static methods which help in the
	implementing of a Formatter for serialization
SerializationInfo	A class that contains all the data needed to serialize
	or deserialize an object

System::Security

The System::Security namespace and the hierarchy of namespaces below it make up a major portion of .NET’s security functionality. System::Web::Security makes up most of the rest. You can break up

.NET security primarily into three different areas: role-based security, code access security, and cryptography.

Role-based security determines what programs may be run based on the role of the user. Code access security adds granularity to .NET security by allowing the CLR to determine what code block within a program can be executed based on evidence of who the user is and the permissions that user may have. Cryptography provides the ability to allow only the users with appropriate keys the ability to read data and code.

I cover .NET security in Chapter 19. Table 5-16 shows all the namespaces within the System::Security namespace hierarchy.

212 C H A P T E R 5 ■ T H E . N E T F R A M E W O R K C L A S S L I B R A R Y

Table 5-16. System::Security Hierarchy Namespaces

Namespace	Description
System::Security	Provides the underlying structure of the CLR
	security system.
System::Security::AccessControl	Provides all the security access information on objects like
	Active Directory, Files, Registry, Mutex, and Semaphores.
System::Security::Authentication	Provides a set of enumerations that describe the secu-
	rity of a connection.
System::Security::Cryptography	Provides cryptographic services, including secure
	encoding and decoding of data. This namespace also
	contains functions, such as hashing, random number
	generation, and message authentication.
System::Security::Permissions	Defines classes that control access to operations and
	resources based on policy.
System::Security::Policy	Contains code groups, membership conditions, and
	evidence.
System::Security::Principal	Defines a principal object that represents the security
	context under which code is running.

System::Threading

Multithread programming can be a very powerful feature, because when coded properly, it allows for more optimal CPU usage and a better perception of response time. Very seldom is a computer at 100 percent usage, and running more than one thread concurrently can help you get more out of your CPU.

The .NET Framework has built-in multithreading. In fact, an important feature of .NET, garbage collection, is handled using multithreading. The .NET Framework exposes its multithreading capabilities with the classes found in the System::Threading namespace. Multithreading, as an important and frequently used feature of the .NET Framework, is found in the mscorlib.dll assembly:

#using <mscorlib.dll>

The System::Threading namespace provides a class to manage groups of threads, a thread scheduler, a class to synchronize mutually exclusive threads, and an assortment of other functionalities to handle multithreading. I cover multithreading in Chapter 16. For now, Table 5-17 lists all the common classes in the System::Threading namespace that you might use.

Table 5-17. Common System::Threading Namespace Classes

Class Name	Description
Interlocked	Provides atomic operations for a shared variable across multiple
	threads
Monitor	Provides a lock for critical sections of a thread, allowing for
	synchronized access
Mutex	Provides synchronized access to shared resources across mutually
	exclusive threads

C H A P T E R 5 ■ T H E . N E T F R A M E W O R K C L A S S L I B R A R Y

213

Table 5-17. Common System::Threading Namespace Classes

Class Name	Description
ReaderWriterLock	Provides a lock that allows a single writer for many readers
Thread	Creates and controls threads
ThreadPool	Provides a pool of efficient worker threads that are managed by the system
Timer	Provides the ability for threads to execute at discrete intervals

System::Web

The System::Web namespace and the hierarchy of namespaces below it make up a major portion of the .NET Framework class library. This makes sense, as .NET came into being because of the Internet and the World Wide Web.

The System::Web hierarchy is too massive to cover fully here, and given that C++/CLI only supports a small portion of the namespaces, those relating to Web services, I only give these namespaces cursory coverage and leave it to the .NET Framework documentation to provide any detailed explanations you need of any particular class. The .NET Framework breaks Web development into two pieces:

Web applications and Web services. I only cover Web services (in Chapter 15) because C++/CLI does not support Web applications, although even this chapter really just scratches the surface of the functionality available to you.

Table 5-18 helps you navigate through the myriad classes provided by the System::Web namespace hierarchy by providing you with a list of some of the more common namespaces that you might use.

Table 5-18. Common System::Web Hierarchy Namespaces

Namespace	Description
System::Web	Contains classes to handle browser–server communications.
	This namespace contains HttpRequest and HttpResponse
	to handle the HTTP dialog between the browser and the
	Web server.
System::Web::Caching	Contains the cache class used to provide caching of
	frequently used data on the Web server.
System::Web::Configuration	Contains classes to help set up the ASP.NET configuration.
System::Web::Hosting	Provides the ability to host managed applications that reside
	outside of the Microsoft Internet Information Services (IIS).
System::Web::Mail	Contains classes to create and send e-mail using either the
	SMTP mail service built into Microsoft Windows 2000 or an
	arbitrary SMTP server.
System::Web::Security	Contains classes to handle ASP.NET security in Web
	applications.
System::Web::Services	Contains classes to create and implement Web services
	using ASP.NET and XML Web service clients.
System::Web::SessionState	Contains classes to store the data specific to a client within
	a Web application, giving to the user the appearance of a
	persistent connection.

214 C H A P T E R 5 ■ T H E . N E T F R A M E W O R K C L A S S L I B R A R Y

Table 5-18. Common System::Web Hierarchy Namespaces (Continued)

Namespace	Description
System::Web::UI	Contains classes and interfaces to create server controls
	and pages for Web applications.
System::Web::UI::HtmlControls	Contains classes to create HTML server controls on Web
	Form pages of Web applications.
System::Web::UI::Imaging	Contains classes to create dynamic images and custom
	image generation services.
System::Web::UI::WebControls	Contains classes to create Web server controls on Web
	pages of Web applications.

System::Windows::Forms

Visual Basic has been using forms for many versions, and Windows Forms is modeled on Visual Basic’s form technology, but with a much finer grain of control. Normally you will create Windows Forms using a drag-and-drop tool, but you also have full access to all aspects of the Win form within your code.

As of the current release, Windows Forms and Windows-based GUI applications are pretty much synonymous. However, if the .NET Framework starts to get ported to other platforms, as it can be, then a Windows Form will be more equivalent to a GUI application.

First off, all the classes that make up the .NET Windows Forms environment are actually found within the System::Windows::Forms namespace. This namespace is large, containing several hundred different types (classes, structures, enumerations, and delegates). You probably will not use every type within the namespace, but there is a good chance that you may use a large number of them, especially if your Windows Form has any complexity involved.

You will cover Windows Forms in detail in Chapters 9 and 10, but you will also see them used many times in subsequent chapters. For those of you who want a head start, Table 5-19 shows a good number of common classes that you will become quite familiar with if you plan to build Windows Forms.

Table 5-19. Common System::Windows::Forms Namespace Classes

Class Name	Description
Application	Provides static methods and properties for managing an application
Button	Represents a Windows Forms Button control
CheckBox	Represents a Windows Forms CheckBox control
CheckListBox	Represents a Windows Forms CheckListBox control
Clipboard	Provides methods to place data in and retrieve data from the system clipboard
ComboBox	Represents a Windows Forms ComboBox control
Control	Represents the base class of all controls in the Windows Forms environment

C H A P T E R 5 ■ T H E . N E T F R A M E W O R K C L A S S L I B R A R Y

215

Table 5-19. Common System::Windows::Forms Namespace Classes

Class Name	Description
Cursor	Represents a Windows Forms cursor
Form	Represents a window or dialog box, which makes up part of the application’s
	user interface
Label	Represents a Windows Forms Label control
LinkLabel	Represents a Windows Forms label control that can display a hyperlink
ListBox	Represents a Windows Forms ListBox control
Menu	Represents the base functionality of all Windows Forms menus
PictureBox	Represents a Windows Forms PictureBox control
RadioButton	Represents a Windows Forms RadioButton control
RichTextBox	Represents a Windows Forms RichTextBox control
ScrollBar	Represents a Windows Forms ScrollBar control
StatusBar	Represents a Windows Forms StatusBar control
TextBox	Represents a Windows Forms TextBox control
ToolBar	Represents a Windows Forms ToolBar
TreeView	Represents a hierarchical display list of TreeNodes

System::Xml

XML is a key component of the .NET Framework. Much of the underlying technological architecture of .NET revolves around XML. No matter what type of application you plan on developing, be it for the Web or a local machine, there is a good chance that somewhere in your application XML is being used. You just might not be aware of it. Because of this, there are a lot of specialized XML classes available to a .NET developer.

To provide XML support to your .NET applications requires the addition of the System.Xml.dll assembly to the top of your source code:

#using <System.Xml.dll>

The .NET Framework provides a developer two different methods of processing XML data: a fast, noncaching, forward-only stream, and a random access in-memory Document Object Model (DOM) tree. You will cover both methods in Chapter 13. You will also see a little bit of XML in Chapter 15.

Table 5-20 shows all of the .NET Framework class library’s XML-related classes that fall within the System::Xml namespace hierarchy.

216 C H A P T E R 5 ■ T H E . N E T F R A M E W O R K C L A S S L I B R A R Y

Table 5-20. Common System::Xml Namespace Classes

Class Name	Description
System::Xml	All the core classes needed to create, read, write, and
	update XML
System::Xml::Schema	Provides XML schema support
System::Xml::Serialization	Provides the ability to serialize .NET managed objects to and
	from XML
System::Xml::Xpath	Provides support for the XPath and evaluation engine
System::Xml::Xsl	Provides support for Extensible Stylesheet Transformations
	(XSLT)

Microsoft::Win32

One namespace within the .NET Framework that I find very helpful at times that does not fall directly under the System namespace hierarchy is the Microsoft::Win32 namespace. There are other namespaces within the Microsoft hierarchy, but they are very specialized, and most likely you will not use them.

To access Microsoft::Win32, you need to reference the mscorlib.dll assembly:

#using <mscorlib.dll>

What makes Microsoft::Win32 unique is that two of its classes, Registry and RegistryKey, provide access to the Windows registry. Although the Windows registry is being used less and less because of .NET’s web.config and application.config files, I still find the registry helpful on some occasions.

Summary

In this chapter, you took a high-level look at the core library provided to .NET developers: the .NET Framework class library. You started by learning the basic structure of the .NET Framework class library. You then moved on to examine many of the namespaces that make up the class library. You will see many of these namespaces in later chapters. You should now have an appreciation of how large the library is and a good idea of how to navigate through it.

In the next chapter, you will look at the very helpful C++/CLI-integrated XML documentation. With this addition, you will be able to make your own documentation that is easy to read, write, and maintain.

C H A P T E R 6

■ ■ ■

Integrated XML Documentation

An important and necessary evil of all software development is documentation. As a programmer I can vouch for the fact that I hate writing documentation—even more so if I have to write both inline and external documentation. If I could remove the necessity to do only one set of documentation, I’d be a much happier camper. With Visual Studio 2005 my wish has finally come true.

What I am referring to is integrated XML documentation.

Integrated XML documentation is a new commenting style introduced in Visual Studio 2005 but new to C++/CLI in that it allows the developer to add documentation internally to the program and then, with a compile switch, to generate external documentation from these new comments. The generated documentation is in the form of XML, which with several third-party tools on the market can be used to build impressive-looking documentation in multiple formats. (I use the de facto standard NDoc, and all generated documentation in this chapter is created using NDoc. You can get more information and download NDoc from http://ndoc.sourceforge.net.)

Integrated XML documentation has always been a part of C#, and I have often wondered why it was excluded from Managed Extensions for C++ as I saw no real reason that it should be left out. I’m sure Visual Basic .NET developers thought the same thing as well. Yes, there are third-party add-ons that added the functionality, but it has taken Microsoft until now to see the light and now it is available to all C++/CLI programmers.

In this chapter I discuss the basics of the new documentation tool, then I show some of the documentation tags available, and finally I present an example that uses all the standard tags provided by the C++/CLI compiler.

The Basics

I have to be one of the first people to admit, I hate documenting my code. It seems like such a waste of time as the code seems so self-explanatory at the time you write it. Of course the function GetDate() gets a date and BuildDataTree() builds a data tree. Isn’t it obvious? Then six months rolls around and the project leader asks you to make a change to your code. You look at the code you wrote and wonder who was the dimwit who wrote this code without documentation? What date is the GetDate() getting and which data tree is the BuildDataTree() building? Then you remember the dimwit is yourself for being too lazy to write reasonable documentation for your code.

The key to documentation as far as I’m concerned is determining what a reasonable amount of documentation is. I’ve seen both extremes on this. I had a colleague who came from an RPG II background and literally commented every line of his COBOL program. If you don’t know COBOL (lucky you!), it is one of the most self-documenting computer languages around, obviously if written properly. Commenting every line is like repeating every sentence in a book.

As you read this book you will see that I am at the other extreme: I only document stuff that I think is unusual or coded in such a way that might cause confusion. This is a very bad habit!

217