Pro Visual C++-CLI And The .NET 2.0 Platform (2006) [eng]
.pdf208 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