The Windows Vista and Windows Server 2008 Developer Story: Run-Time Status and Control (RSCA) API

Microsoft Corporation

April 2006
Revised January 2007

The Windows Vista and Windows Server 2008 Developer Story includes content for developers, and other technology experts and managers, interested in an in-depth exploration of some of the new and extended features in Windows Vista. It is released to the Windows Vista Developer Center in the form of Articles, published approximately one every two weeks. Those Articles are only a summary of the Windows Help file, which can be downloaded here.

Note   To provide feedback about the articles, please send e-mail to Vistadev@microsoft.com.

Contents

Introduction
Using RSCA
Resources
See Also

Introduction

The Run-time Status & Control (RSCA) API is a new programmatic interface for accessing and manipulating the runtime state of Web sites, application domains, applications, worker processes, the currently running requests, and so on. It does not include configuration or performance data. Much of this information is not available from existing management interfaces—such as Active Directory Service Interfaces (ADSI) or Windows Management Instrumentation (WMI)—and was only available in past versions of IIS through volatile metabase properties.

Although RSCA provides information about both native and managed Web applications, the API itself is targeted to the COM/C++ developer. It is available under IIS 7 only and its interface is declared in the header file rscaps.h supplied in the Windows SDK. The RSCA runtime is a client-loaded DLL (rsca.dll) that communicates with the Windows Activation Service (WAS) and the IIS engine to access and modify current state. RCSA generally allows only very coarse manipulation of state (for example, initialize, start, stop, and recycle).

Using RSCA

Although RSCA is relatively small and straightforward, there are a number of considerations for its proper use:

• Although RSCA can provide information about managed domains and applications, the API does not force the instantiation of an application domain or application object if they do not already exist. In this case, RSCA returns an E_NOT_IMPL error.
• It is important to remember that when instantiating objects, their state reflects the state of the corresponding Web entity at the point of instantiation. With time, the state of the object may become stale. To ensure that the state of an object is current, either call its RefreshState method or dispose the object and obtain a new reference to or instantiation of it.
• Worker processes are especially dynamic, being designed to be created and terminated as required to perform their assigned tasks. If a process ID (PID) for a terminated process is passed to a RSCA method, the method should return ERROR_NOTFOUND. In response, the developer should release the associated IRSCA_WorkerProcess object and verify the list of current worker processes.
• Follow the conventions of good COM programming by adding and releasing references, and allocating and deallocating storage whenever necessary.

For more information, see Run-Time Status and Control Reference in the Windows SDK.

Resources

The following interfaces (C++ classes containing only methods) comprise RSCA. They contain two enumerations (RSCA_OBJECT_STATE_ENUM and RSCA_WORKER_PROCESS_STATE_ENUM) and the IRSCA_RequestReader structure.

See Also

Internet Information Services

IIS Manager

IIS Modules

HTTP Server API (coming soon)