Category list

- page 13

Summary

This book describes the many ways the CLR can be customized to satisfy the unique requirements of your application. Throughout this book, these customizations are described within the context of CLR hosts and other extensible applications. A CLR host is an application that uses the CLR hosting APIs to customize the CLR. Examples of CLR hosts include SQL Server 2005, Internet Explorer, and ASP.NET.

Now that I've defined some basic terms and discussed the typical architecture of an extensible application, let's get started with a broad overview of what you can achieve by customizing the CLR using the hosting APIs.

Chapter 2. A Tour of the CLR Hosting API

The common language runtime (CLR) hosting API is a set of unmanaged functions and interfaces that a host uses to customize the CLR for its particular application model. Because the CLR has been designed to adapt to a variety of application scenarios, the amount of customization available through the hosting APIs is quite extensive . In most cases, you'll find that your scenario requires only a subset of the total functionality provided by the API. The overview of the hosting API provided in this chapter is intended to give you an idea of the possible customization options so that you can decide which ones apply most to your application's requirements.

Most of the individual features introduced here have entire chapters dedicated to them later in the book. This chapter merely provides the big picture. In addition to explaining the features, I'll describe the design pattern used in the interfaces and provide enough background and samples to get you started using them.

The hosting API is defined in the file mscoree.idl, which can be found in the Include directory in the Microsoft .NET Framework software development kit (SDK). These programming interfaces consist of both unmanaged functions and a set of COM interfaces. The unmanaged functions are public exports from mscoree.dll. Most of these functions are used primarily for CLR initialization, but some are used to discover basic information about the CLR after it is running, such as which version was loaded and where the CLR installation resides on disk.

CorBindToRuntimeEx and ICLRRuntimeHost

The primary unmanaged function you'll use is CorBindToRuntimeEx . This function is used to initialize the CLR into a process and is therefore the first of the hosting APIs you're likely to call. One of the return parameters from CorBindToRuntimeEx is a pointer to an interface named ICLRRuntimeHost the initial COM interface in the hosting API. I say " initial " because ICLRRuntimeHost is the first interface you'll use when hosting the CLR. Given an interface pointer of type ICLRRuntimeHost , you gain access to all the other hosting functionality provided by the API. Figure 2-1 provides a sampling of the breadth of functionality a CLR host can access given a pointer to the ICLRRuntimeHost interface.

Figure 2-1. The CLR hosting interfaces as the gateway to the managed environment

Because of its role as the initial interface that hosts use to customize the CLR, ICLRRuntimeHost plays a part in every CLR host you'll write. As such, this interface will show up in one way or another in almost every chapter in this book. Table 2-1 provides an overview of the capabilities of ICLRRuntimeHost by briefly describing each method. The table also describes where in the book to look for more detail about each method.

Table 2-1. The Methods on ICLRRuntimeHost

Method	Description
Start	Starts the CLR running in a process. Details provided in Chapter 3.
Stop	Stops the CLR once it has been loaded into a process. Details provided in Chapter 3.
GetHostControl	Used by the CLR to discover which other interfaces the host implements. This method is described in more detail later in this chapter. See the "Hosting Manager Discovery" section.
GetCLRControl	Used by a CLR host to obtain a pointer to one of the hosting interfaces implemented by the CLR. This method is described in more detail later in this chapter. See the "Hosting Manager Discovery" section.
UnloadAppDomain	Unloads an application domain from the process. Details provided in Chapter 5.
GetCurrentAppDomainId	Returns the unique numerical identifier for the application domain in which the calling thread is currently running. I discuss this method and the overall role of application domain identifiers in Chapter 5.
ExecuteInDomain	Executes a callback function in a particular application domain.See Chapter 7 for details.
ExecuteApplication	Executes an application defined by a formal application manifest. Application manifests are a new concept in Microsoft .NET Framework 2.0. I don't cover application manifests or the ExecuteApplication method at all in this book. See the Microsoft .NET Framework SDK for details.
ExecuteInDefaultAppDomain	Executes a given method in the default application domain. This method is handy for CLR hosts that use only one application domain. This method is discussed more in Chapter 7.

Flylib.com