OReilly COM and dot NET component services sep 2001 ISBN 0596001037 pdf

COM+ Queued Com ponents 8.1 Maj or Benefits of Queued Com ponents 8.2 Queued Com ponents Architecture 8.3 Com ponent Services Explorer Configurat ion 8.4 I nvoking Queued Com ponents

COM and NET Com ponent Services

Dedication

Foreword

Preface

Scope of This Book

Som e Assum pt ions About t he Reader

Definitions and Text Convent ions

Ot her COM+ Books and References

How to Contact Us

Acknowledgm ents

1 COM+ Com ponent Services

1.1 COM+ Com ponent Services

1.2 The Com ponent Services Explorer

1.3 Hello COM+

1.4 COM+ Configured Com ponents

1.5 Applications, DLLs, and Com ponents

1.6 Configuring COM+ Applications

1.7 Debugging COM+ Applications

1.8 Deploying COM+ Applications

1.9 Sum m ary

2 COM+ Context

2.1 Encapsulat ion via Marshaling in COM

2.2 Encapsulat ion via I ntercept ion in COM+

2.3 The Cont ext Obj ect

2.4 The Call Obj ect

2.5 Cross- Context Manual Marshaling

2.6 Sum m ary

3 COM+ I nstance Managem ent

3.1 Client Types

3.2 I nstance Managem ent and Scaling

3.3 Obj ect Pooling

3.4 Just- in-Tim e Activation

3.5 Com bining JI TA with Obj ect Pooling

3.6 Obj ect Constructor String

3.7 COM+ I nstance Managem ent Pitfalls

4.6 Vot ing on a Transaction

4.7 Transactional Obj ect Life Cycle

4.8 Designing Transactional Com ponents

4.9 Nont ransactional Clients

4.10 Transactions and Obj ect Pooling

4.11 Com pensating Transactions

4.12 Transaction Execution Tim e

4.13 Tracing Transactions

4.14 I n-Doubt Transactions

4.15 Transaction Stat istics

4.16 COM+ Transactions Pitfalls

5 COM+ Concurrency Model

5.1 Obj ect- Oriented Program m ing and Multiple Threads

5.2 Apartm ents: The Classic COM Solut ion

5.3 Act ivities: The COM+ I nnovat ion

5.4 COM+ Configurat ion Sett ings

5.5 Act ivities and JI TA

5.6 Act ivities and Transactions

5.7 Tracing Activit ies

5.8 The Neutral Threaded Apartm ent

5.9 Sum m ary

6 Program m ing t he COM+ Catalog

6.1 Why Program the Catalog?

6.2 The Catalog Program m ing Model

6.3 Catalog St ructure

6.4 I nt eract ing with t he Catalog

6.5 Features of COMAdm inCatalog

6.6 The COM+ Catalog and Transactions

6.7 Sum m ary

7 COM+ Security

7.1 The Need for Security

7.2 Basic Security Term s

7.3 Role- Based Security

7.4 Securing a Server Application

7.5 Securing a Library Application

7.6 Program m atic Role-Based Security

7.7 Security Boundaries

7.8 Advanced COM+ Security

7.9 COM+ Security Pitfalls

7.10 Sum m ary

8 COM+ Queued Com ponents

8.1 Maj or Benefits of Queued Com ponents

8.2 Queued Com ponents Architecture

8.3 Com ponent Services Explorer Configurat ion

8.4 I nvoking Queued Com ponents on the Client Side

8.5 Designing Queued Com ponent I nterfaces

8.6 Receiving Output from a Queued Com ponent

8.7 Queued Com ponent Error Handling

8.8 Queued Com ponents and Transactions

8.9 Synchronous Versus Asynchronous Com ponents

8.10 Queued Com ponents Security

8.11 Queued Com ponents Pitfalls

8.12 Sum m ary

9 COM+ Event Service

9.1 Classic COM Events

9.2 COM+ Event Model

9.3 The Event Class

9.4 Subscript ion Types

9.5 Delivering Events

9.6 Event Filtering

9.7 Distributed COM+ Events

9.8 Asynchronous Events

9.9 COM+ Events and Transactions

9.10 COM+ Events and Securit y

9.11 COM+ Events Lim itat ion

9.12 Sum m ary

10 .NET Serviced Com ponents

10.1 Developing Serviced Com ponents

10.2 NET Assem blies and COM+ Applicat ions

10.3 Registering Assem blies

10.4 Configuring Serviced Com ponents

10.5 Application Activation Type

10.6 The Description Attribute

10.7 Accessing the COM+ Context

10.8 COM+ Cont ext Attributes

10.9 COM+ Obj ect Pooling

10.10 COM+ Just- in-Tim e Activat ion

10.11 COM+ Constructor St ring

10.12 COM+ Transactions

10.13 COM+ Synchronization

10.14 Program m ing t he COM+ Catalog

10.15 COM+ Security

10.16 COM+ Queued Com ponents

10.17 COM+ Loosely Coupled Events

10.18 Sum m ary

A The COM+ Logbook

A.1 Logbook Requirem ents

A.2 Log File Exam ple

A.3 Using the Logbook

A.4 Configuring t he Logbook

A.5 How Does the Logbook Work?

A.6 Sum m ary

B COM+ 1.5

B.1 I m proved User I nterface Usability

B.2 Legacy Applications and Com ponents

B.3 Disabling Applicat ions and Com ponents

B.4 Pausing Applicat ions

B.5 Service Activat ion Type

B.6 I m proved Queuing Support

B.7 Application Pooling and Recycling

B.8 Application Dum p

B.9 Application Part itioning

B.10 Aliasing Com ponents

B.11 Configurable Transaction I solat ion Level

B.12 I m proved Context Act ivat ion Set ting

B.13 Private Com ponents

B.14 Web Services in COM+ 1.5

B.15 Sum m ary

C I ntroduction to NET

C.1 NET Program m ing Languages

C.2 Packaging NET Com ponents: Assem blies

C.3 Developing NET Com ponents

C.4 Writing NET Client- Side Code

C.5 NET as a Com ponent Technology

C.6 Com posing Assem blies

Colophon

Dedication

To m y wife, Dana

Forew ord

I first ran into COM+ back in 1996 I n those days, I was working as

a Com m on Object Request Broker Architecture ( CORBA) consultant and was fresh out of I BM, where I had been heavily involved in

I BM’s original CORBA im plem entation

CORBA was the first of the architectures that we m ight describe today as Distributed Com ponent architectures, which set the stage for both COM/ DCOM in the Microsoft space and RMI / I I OP in the Java space

Back then, I was int erested in a particularly knotty problem related

to distributed com ponent architectures System s built with such architectures had a characteristic perform ance pattern They could handle large num bers of transact ions, as long as those transactions originated from a sm all num ber of clients So, for exam ple, 5,000 transact ions per m inute divided between 5 clients worked fine But when those sam e 5,000 transactions per m inute were split am ong 1,000 clients, each processing 5 transactions per m inute, t he

system s choked

This was odd, I t hought Why should 5 clients, each processing 1,000 transactions per m inute, be fundam entally different than 1,000 clients, each processing 5 transactions per m inute? What is the difference between the first 5,000 transactions per m inute and the second?

Distributed com ponent architectures, as they existed in 1996,

dictated a one- to- one relationship between clients and com ponent instances The business logic of such architectures is in the

com ponent instances And it is the business logic that m akes

transact ional requests of transactional resources, such as the

database I n order to m ake transactional requests, the com ponent instances require expensive resources, such as database

connections We run out of steam ( i.e., transactional throughput) when one of two things happen: we overload the system with

transact ional requests or we run out of resources ( e.g., database connections)

Clearly, going from 5 clients, each m aking 1,000 transactional

requests per m inute, to 1,000 clients, each m aking 5 transactional requests per m inute, has no overall im pact on the transactional throughput Therefore, the reason why our distributed com ponent system s m ust be dying is that we are running out of resources

So the answer to getting lots of clients on a distributed com ponent architecture is not going to com e from increased capability of the back- end transactional resources ( e.g., databases) I t will have to com e from som ething else- som ething that allows resource sharing This, t hen, is the problem I worked on back in 1996 How do you

get several clients to share resources in a distributed com ponent architecture?

The solution to this problem cam e from an unexpected source I was asked to write a book on COM and DCOM I knew very lit tle about COM and DCOM back then As I looked over the COM/ DCOM white papers on the Microsoft web site, I quickly recognized it as a typical distributed com ponent architect ure and predicted the sam e throughput problem s I had seen in other distributed com ponent system s

As I browsed through the white papers, I noticed an obscure beta product called Microsoft Transaction Server ( MTS) At first, I

dism issed MTS as an API used to m anage distributed transactions But as I read m ore about MTS, I realized that it had little to do with transact ions I nstead, it attacked a m uch m ore interesting problem : how to share resources am ong clients I n a nutshell, MTS addressed the very problem that had so vexed the existing distributed

com ponent system s- how to support a large num ber of

low-transact ion generating clients!

I did eventually write that book, as well as m any articles on the

im portance of the ideas introduced by MTS Many of these articles appeared in m y ObjectWatch newslet ter ( available at

www.objectwatch.com) , a newsletter t hat has, over tim e, becom e influential in its space

Back in 1996, I predicted that MTS would be a historically im portant product- one that would redefine approaches to scalability in

distributed com ponent system s I n fact , that prediction has com e true Today, every infrastructure designed to support high

scalability in distributed com ponent system s is based directly on the ideas, algorithm s, and principals first introduced by MTS in 1996 Enterprise JavaBeans, for exam ple, the Java scalability

infrastructure, is alm ost a direct copy of MTS

But what does this have to do with COM+ , you m ay ask I t turns out that COM+ and MTS are one and the sam e Microsoft, never known for its m arketing savvy, decided to wait unt il custom ers finally got used to the nam e MTS ( itself a m isleading nam e) , and then it pulled a fast one- it switched the nam e! And not just any nam e, but one that would be as confusing as possible! So they renam ed MTS as COM+ Naturally, custom ers assum ed that COM+ was the next release of COM I n fact , COM+ was the next release of MTS

Now Microsoft has announced NET Once again, the brilliant

Microsoft m arketing organization has left m any custom ers confused

I s COM+ now dead? Far from it—.NET is a series of interesting new features, none of which replace COM+ COM+ is st ill the scalable infrastructure that supports resource sharing and deals with the

m yriad of issues ( such as security and transaction boundary

m anagem ent) that are so closely related to resource sharing and so crucial to distributed applications

So whether you are rushing into Microsoft’s new NET technology platform or taking a wait and see attitude, if you need to put a lot of clients around your system , you need to understand COM+

Therefore, this book is very tim ely COM+ is going to be with us for

a long tim e I ts nam e m ay change again, just to confuse the

innocent; but t he ideas, algorithm s, and principals will not COM+ , under whatever nam e, is here to stay!

Roger Sessions,

CEO, ObjectWatch, I nc

Publisher, ObjectWatch newsletter (www.objectwatch.com)

Author, COM+ and the Battle for the Middle Tier

Austin, Texas

Preface

This book discusses COM+ com ponent services Each service is covered in its own chapter, and each chapter discusses a sim ilar range of issues: the problem the service addresses, possible

solutions to that problem , an in- depth description of the COM+ solution, tradeoffs, design, and im plem entation guidelines, tips, and known pitfalls I have tried to provide useful design inform ation and lessons I learned while applying COM+ I also describe COM+ helper classes and ut ilities I developed that will enhance your productivity significantly ( The COM+ Events helper objects and the COM+

Logbook are prim e exam ples.) This book focuses on the "how to"—that is, it provides practical inform ation You should read the

chapters in order, since m ost chapters rely on inform ation discussed

in t he preceding chapters The book also aim s to explain COM+ step

by step A software engineer already fam iliar with COM who wants

to know what COM+ is and how to use it can read this book and start developing COM+ applications im m ediately

Scope of This Book

Here is a brief sum m ary of the chapters and appendixes in this book:

• Chapter 1 introduces the Com ponent Services Explorer and basic COM+ term inology This chapter deliberately holds your hand as you develop your first "Hello World" COM+

com ponent Subsequent chapters do m uch less handholding and assum e you are fam iliar with the COM+ environm ent I f you already have experience with basic COM+ developm ent, feel free to skip this chapter

• Chapter 2 dem ystifies the COM+ context by presenting it as the key m echanism for providing com ponent services using call interception Generally, you need not be concerned with contexts at all However, the COM+ context underlies the way COM+ services are im plem ented

• Chapter 3 describes two scalability- enabling m echanism s that COM+ provides for a m odern enterprise application: object pooling and Just- in-Tim e Activation ( JI TA) The discussion of instance m anagem ent, and especially JI TA, is independent of transact ions Early COM+ docum entation and books tended to couple instance m anagem ent and transactions However, I found that not only can you use instance m anagem ent

independently of transactions, but it is easier to explain it that

way Besides explaining how to best use object pooling and

JI TA, Chapter 3 describes other activation and instance

m anagem ent COM+ services such as the constructor string

• Chapter 4 explains t he difficult, yet com m on, problem s that transact ions address, and provides you with a distilled

overview of transaction processing and the transaction

program m ing m odel The difficult part of writing this chapter was finding a way to convey the right am ount of transaction processing theory I want to help you understand and accept the resulting program m ing m odel, but not bury you in the details of theory and COM+ plum bing This chapter focuses on COM+ transaction architecture and the resulting design

considerations you have to be aware of

• Chapter 5 first explains t he need in the com ponent world for a concurrency m odel and the lim itations of the classic COM solution I t then describes how the COM+ solution, activities,

im proves deficiencies of apartm ents

• Chapter 6 shows how to access com ponent and application configuration inform ation program m atically using t he COM+ Catalog interfaces and objects Program m atic access is

required when using som e advanced COM+ services and to autom ate setup and developm ent tasks This chapter provides you with com prehensive catalog struct ure diagram s, plenty of sam ple code, and a handy utility

• Chapter 7 explains how to secure a m odern application using the rich and powerful ( yet easy to use) security infrastructure provided by COM+ This chapter defines basic security

concepts and shows you how to design security into your application from the ground up You can design this security

by using COM+ declarative security via the Com ponent

Services Explorer and by using advanced program m atic

chapter addresses required changes to the program m ing

m odel I f you have ever had to develop an asynchronous

m ethod invocation option for your com ponents, you will love COM+ queued com ponents

• Chapter 9 covers COM+ loosely coupled events, why there is

a need for such a service, and how the service ties into other COM+ services described in earlier chapters ( such as

transact ions, security, and queued com ponents) Many people consider COM+ events t heir favorite service I f you have had

to confront COM connection points, you will appreciate COM+ Events

• Chapter 10 shows how NET com ponent s can take advantage

of the com ponent services described in the previous chapters

I f you are not fam iliar with NET, I suggest you read Appendix

C first—it contains an introduction to NET and C# Chapter

10 repeats in C# m any of the C+ + or VB 6.0 code sam ples found in earlier chapters, showing you how to im plem ent them in NET

• Appendix A helps you develop a useful and im portant ut ility—

a flight recorder that logs m ethod calls, errors, and events in your application Logging is an essential part of every

application and is especially im portant in an enterprise

environm ent The logbook is also an excellent exam ple of the synergies arrived at by com bining m ultiple COM+ services I t

is also a good representation of the design approaches you

m ay consider when com bining services

• Appendix B describes the changes, im provem ents, and

enhancem ents introduced to COM+ in the next release of Windows, Windows XP I nstead of writing the book as if

Windows XP were available now ( as of this writ ing it is only in beta) , I chose to write the book for the developer who has t o deliver applications today, using Windows 2000 When you start using Windows XP, all you need to do is read Appendix B—it contains the additional inform ation you need

• Appendix C describes the essential elem ents of the NET

fram ework, such as the runt im e, assem blies, and how to develop NET com ponents The appendix allows a reader who

is not fam iliar with NET to follow Chapter 10

Som e Assum ptions About the Reader

I assum e that you are an experienced COM developer who feels com fortable with COM basics such as interfaces, CoClasses, and apartm ents This book is about COM+ com ponent services, not the com ponent technology used to develop a COM/ DCOM or NET

com ponent You can still read the book without this experience, but you will benefit m ore by having COM under your belt I assum e you develop your com ponents m ost ly in C+ + and ATL and that you write occasional, sim ple client code in Visual Basic I also use trivial C# in Chapter 10 to dem onstrate how NET takes advantage of COM+ services, but you don't need to know C# to read that

chapter A NET developer should also find this book useful: read and understand the services in Chapter 1 through Chapter 9, and then use Chapter 10 as a reference guide for the syntax of NET attributes

Definitions and Text Conventions

The following definit ions and conventions apply throughout this book:

• A com ponent is an im plem entation of a set of interfaces A com ponent is what you m ark in your I DL file ( or type library) with CoClass or a class in C#

• An object is an inst ance of a com ponent You can create

objects by calling CoCreateInstance( ) in C+ + , specifying the class I D ( the type) of the object you want to create I f you use Visual Basic 6.0, you can create objects using new or CreateObject( ) A C# client uses new to create a new

instance of a com ponent

• I use the following term s in the book: CoCreating refers to calling CoCreateInstance() in C+ + , or new or

CreateObject( ) in Visual Basic Querying an object for an interface refers to calling IUnknown::QueryInterface( ) on the object Releasing an object refers to calling

IUnknown::Release( ) on the object

• The graphical notat ions in Figure P-1 are used in alm ost every design diagram in t he book The "lollipop" denotes an

interface, and a m ethod call on an interface is represented by

an arrow beginning with a full circle

Figure P- 1 I nt erface and m et hod call graphical notat ions

• Error handling in the code sam ples is rudim entary The code sam ples serve to dem onstrate a design or a technical point, and cluttering them with too m uch error handing would m iss the point I n a production environm ent, you should verify the returned HRESULT of every COM call, catch and handle

exceptions in C# , and assert every assum ption

I use the following font conventions in this book:

• I talic is used for new term s, citations, online links, filenam es,

directories, and pathnam es

• Constant width is used to indicate com m and- line com put er output and code exam ples, as well as classes, constants, functions, interfaces, m ethods, variables, and flow- controlled statem ents

• Constant-width bold is used for code em phasis and user

input

• Constant-width italic is used to indicate replaceable

elem ents in code st atem ents

This icon indicates a note or tip

This icon indicates a warning

Other COM+ Books and References

This book describes how to use COM+ com ponent services in your application I t focuses on how to apply the technology, how to avoid specific pitfalls, and design guidelines I f you want to know m ore about COM+ in general and the nature of com ponent technology, I recom m end the following two books that helped m e a great deal in

m y attem pt to grasp COM+

COM+ and the Battle for the Middle Tier by Roger Sessions ( John

Wiley & Sons, 2000) is hands down the best "why" COM+ book I t explains in detail, with excellent exam ples and in plain language, the need for software com ponents and com ponent services For exam ple, instead of the page or two this book includes on t he

m otivation for using transactions, Sessions devotes two fascinating chapters to the topic The book goes on to com pare existing

com ponent technologies ( such as COM, CORBA, and Java) and their corresponding suites of com ponent services I t also contains a few case studies from real- life system s that use COM+ Roger Sessions also has a unique way of eloquently nam ing things— providing the

m ost appropriate term , which is often not the nam e Microsoft uses Whenever it m akes sense, this book uses Sessions' term inology, such as "instance m anagem ent" instead of the Microsoft term

"activation."

Understanding COM+ by David S Platt ( Microsoft Press, 1999) is

probably the best "what" COM+ book The book describes the

services available by COM+ and provides sidebar sum m aries for the busy reader I t is one of the first COM+ books, and Platt worked on

it closely with t he COM+ team

I also used the MSDN Library extensively, especially the

"Com ponent Services" section, while writing this book Alt hough the inform ation in this library tends to be terse, the overall structure is good Use this book to learn how to apply COM+ productively and

effectively, and use the MSDN Library as a reference for technical details and a source for additional inform ation

How to Contact Us

We have tested and verified the inform ation in this book to the best

of our ability, but you m ay find that features have changed ( or even that we have m ade m istakes!) Please address com m ents and

questions concerning this book to the publisher:

O’Reilly & Associates, I nc

The web site for the book lists exam ples, errata, and plans for

future editions You can access this page at:

http: / / www.oreilly.com / catalog/ com dotnetsvs

To ask technical questions or com m ent on this book, send em ail to: bookquestions@oreilly.com

Or to m e directly:

juval.lowy@com ponentware.net

For m ore inform ation about our books, conferences, software,

resource centers, and the O’Reilly Net work, see our web site:

http: / / www.oreilly.com

Acknow ledgm ents

A book is by no m eans the product of just the author’s work I t is the result of m any events and individuals, like links in a chain I cannot possibly nam e everyone, ranging from m y parents to m y friends I am especially grateful for m y two friends and colleagues, Marcus Pelletier and Chris W Rea Marcus worked with m e on large COM+ projects, and together we confronted the unknown Marcus’s thoroughness and technical expertise is a m odel for every

program m er Chris’s com m ents and insight into a reader’s m ind have contributed greatly to this book’s accuracy, integrity, and flow

I wish to thank Yasser Shohoud for verifying m y approach to

transact ion processing and sharing with m e his own, Richard Grim es for reviewing the book, and Roger Sessions for writing the

Foreword Thanks also to Johnny Blum enstock for providing m e with

a place to write Finally, this book would not be possible without m y

wife, Dana, whose constant support and encouragem ent m ade this book a reality Thank you, Dana

Chapter 1 COM+ Com ponent Services

By now, m ost developers of large- scale enterprise applications are convinced of the benefits of com ponent- oriented developm ent They have discovered that by breaking a large system down into sm aller unit s, they can writ e code that is easier to reuse on other projects, easier to distribute across m ult iple com puters, and easier to

m aintain As long as these com ponents adhere to a binary standard that defines how t hey com m unicate with one another, they can be invoked as needed at runtim e and discarded when they have

finished their work This type of application is also particularly

suited to the Web, where clients request services of rem ote

applications and then, once satisfied, m ove on to other tasks

For nearly a decade, the Microsoft Com ponent Object Model ( COM) has been the standard for com ponents that run on Windows

m achines, including Windows 9x and Me clients and Windows NT and 2000 servers The COM m odel is well docum ented by the

Microsoft Com ponent Object Model Specification Tools such as Visual C+ + and Visual Basic m ake it easy to create COM

com ponents, and scores of books, training classes, and articles are available to teach program m ers how to use them Many features of the Windows operating system are now im plem ented as COM

com ponents, and m any com panies have invested heavily in based system s of their own

COM-I n July 2000, Microsoft announced a radically new com ponent m odel

as part of its NET developm ent platform , suddenly calling into

question the viabilit y of existing COM applications .NET com ponents bear little resem blance to legacy COM com ponents and are not backwards com patible They can be m ade to interoperate with COM com ponents but do not do so naturally

When it com es to the services and tools program m ers use to build enterprise- scale NET applications, however, one facility continues

to provide the necessary runtim e infrastructure and services: COM+ com ponent services These services have been available on

Windows 2000 since its release, but they will gain greater

im portance in t he m onths ahead As it t urns out, they offer a bridge between traditional COM and NET applications, m aking your

understanding and m astery of them as im portant now as it has ever been

I n this chapter, we provide a quick overview of the COM+ suite of com ponent services and then introduce you to the Com ponent

Services Explorer, your prim ary tool for building and m anaging both COM and NET enterprise applications You will also create, debug, and deploy a sim ple COM+ "Hello World" application, using a

traditional COM com ponent and learning about COM+ application types and configured com ponents as you do so

1 1 COM+ Com ponent Services

Com ponents need runtim e services to work The original COM

runtim e supported com ponents located on the sam e m achine,

typically a desktop PC As the focus of Windows developm ent

shifted from standalone PCs to networked system s, Microsoft found

it necessary to add additional services (see The Evolution of COM+ Services) First, they added support for distributed applications, or applications whose com ponents are located on m ore than one

m achine ( som etim es referred to as "COM on a wire") Later,

Microsoft added new services to support enterprise applications,

whose com plexity and scale placed new dem ands on the resources

of a system and required an entirely new level of support These trends were only exacerbated by the m ove to web- based

applications aim ed at huge num bers of custom ers connect ed over the public I nternet

Collectively, the services that support COM and NET com

ponent-based applications are known as the COM+ com ponent services, or

sim ply as COM+

The Evolution of COM+ Services

COM solved a num ber of problem s facing early com ponent

developers by providing a binary standard for com ponents,

defining a com m unication interface, and providing a way to

link com ponents dynam ically COM freed developers from

having to deal with "plum bing" and connectivity issues,

allowing them to concentrate on designing com ponents

By the m id- 1990s, however, it was clear that Windows

developers needed additional services to support distributed

and transaction- oriented applications Distributed COM

( DCOM) was released in 1995, a specification and service

used to distribute com ponents across different m achines and

invoke them rem otely Then, Microsoft released the Microsoft

Transaction Server ( MTS) in 1998, which provided

com ponent developers with new services for transaction

m anagem ent, declarative role- based security, instance

activation m anagem ent, com ponent deploym ent and

installation, and an adm inistration tool for m anaging

com ponent configurations

There was m ore to MTS than just new services MTS

represented a program m ing m odel in which the com ponent

developer sim ply declared ( using the MTS adm inistrative

tool) which services a com ponent required, and left it to MTS

to provide an appropriate runtim e environm ent Developers

could now spend even less effort on low- level service

plum bing ( such as interacting wit h transaction processing

m onitors or m anaging the life cycle of an object) , and m ore

on the business logic the custom er paid for Yet, MTS had it s

lim itations Forem ost was t he fact that MTS was built on top

of conventional COM/ DCOM The underlying operating

system and COM itself were unaware that MTS even existed

MTS resorted to esoteric hacks and kludges to provide its

services, and MTS could not provide its services to every

COM object ( m ultithreaded apartm ent objects were

excluded) Som e services, such as object pooling, were

either not possible or unavailable

The developm ent of a new version of the Windows NT

operating system ( init ially called NT 5.0 and later renam ed

Windows 2000) , gave Microsoft an opportunity to correct the

deficiencies of MTS and DCOM by fusing them into a new

com prehensive com ponent services suit e Microsoft added

yet m ore services, including object pooling, queued

com ponents, and events, and m ade the package a part of

the core Windows operating system The new suite of

services was nam ed COM+ 1.0, the subject of this book The

next version of COM+ , COM+ 1.5, is scheduled for release

with Windows XP in Q4 2001 and is described in Appendix B

The COM+ acronym is an overloaded and often m isused

term Today it is used inform ally to refer to both the latest

version of the COM com ponent specification and the

com ponent services available on the lat est versions of

Windows I n this book, we use the term COM+ to refer to the

COM+ com ponent services When we speak of COM+

com ponents, we refer to COM com ponents configured to run

under those services However, as you will see, a COM+

application m ay consist of either COM or NET com ponents

( see COM+ : The Migration Path to NET)

Here is a quick sum m ary of the m ost im portant services provided

by COM+ :

Adm inistration

Tools and services that enable program m ers and

adm inistrators to configure and m anage com ponents and com ponent-based applications The m ost im portant tool is the Microsoft Managem ent Console Com ponent Services Explorer COM+ also provides a standard location, the COM+ Catalog, for storing configuration inform at ion The Com ponent Services Explorer is explained in the following section The COM+

Catalog is described in Chapter 6

Just- in- Tim e Activation (JI TA)

Services that instantiate com ponents when they are called and discard them when their work is done JI TA is explained

in Chapter 3

Object pooling

Services that allow instances of frequently used, but

expensive, resources, such as database connections, to be

m aintained in a pool for use by num erous clients Object pooling can im prove the perform ance and responsiveness of a distributed application dram atically I t is explained in Chapter

3

Transactions

Services that allow operations carried out by distributed

com ponents and resources such as databases to be treated as

a single operation Transaction m anagem ent is a requirem ent

of m ost com m ercial system s COM+ Transaction services are discussed in Chapter 4

Services that allow com ponents to com m unicate through asynchronous m essaging, a feature that m akes possible

loosely coupled applications or even disconnected

applications Queued com ponents are discussed in Chapter 8

Events

Services that allow com ponents to inform one another of significant events, such as changes in data or system state COM+ supports a publish- subscribe m odel of event

notification, which is described in Chapter 9

To sum m arize, COM+ is about com ponent services and has alm ost nothing to do with t he way a com ponent is developed The NET fram ework allows you to develop binary com ponents m ore easily than does COM, but it continues to rely on com ponent services available through COM+ The m anner in which NET and COM

com ponents are configured to use these services, however, is not the sam e Currently, m ost Windows enterprise developers are

developing applications based on the existing COM standard using Visual Basic 6 and Visual C+ + 6 with ATL For this reason, t his book uses COM exam ples to dem onstrate COM+ However, these sam e services are available to NET com ponents as well Chapter 10

shows you how to use them

COM+ 1.0 is an integral part of Windows 2000 and requires no special inst allation Som e COM+ features are available only when

both the client and server are running on Windows 2000 m achines, but COM+ clients can usually run on Windows 9.x and Windows NT

m achines as well

COM+ : The Migration Path to NET

.NET is Microsoft’s next-generation com ponent technology

and application developm ent platform ( For a quick overview

of the NET platform , see Appendix C.) However, adopting a

radically new technology such as NET is never an easy

endeavor for com panies and developers Most have m ade a

considerable investm ent in an existing, often COM- based,

code base and the developer skills needed to m aintain it

Unless com panies have a com pelling reason to m ove to NET

or a reasonable m igration path, they postpone or avoid

m aking the change

However, because COM and NET com ponents can coexist in

the sam e COM+ application, com panies can cont inue to build

COM com ponents today, adding NET serviced com ponents to

their applications at a later t im e when t he advantages of

doing so are m ore com pelling This is a m igration strategy

worth your consideration

When Windows XP is released in Q4 2001, it will include a new version of COM+ com ponent services, COM+ 1.5 This new version

im proves COM+ 1.0 usability and addresses som e of the pitfalls of using COM+ 1.0 on Windows 2000, as described in this book COM+ 1.5 also adds new features to existing services and lays the

foundation for integration wit h NET web services Appendix B

sum m arizes the fort hcom ing changes

1 2 The Com ponent Services Explorer

COM+ com ponents and applications are m anaged through the

Com ponent Services Explorer ( form erly known as the COM+

Explorer) The Com ponent Services Explorer is a Microsoft

Managem ent Console snap- in and is available on every Windows

2000 m achine

To fire up the Com ponent Services Explorer, go to the Start m enu and select Settings Control Panel When the Control Panel window appears, select the Adm inistrative Tools directory and then select the Com ponent Services application

The first thing you should do after locating the Com ponent Services Explorer is create a shortcut to it on your desktop As a developer, you need easy access to the Com ponent Services Explorer, your

m ain gateway into COM+ ( see Figure 1- 1) You can use the

Com ponent Services Explorer to create and configure COM+

applications, im port and configure COM or NET com ponent s, export and deploy your applications, and adm inister your local m achine You can even adm inister COM+ on other m achines on the network, provided you have adm inistrative privileges on those m achines

A COM+ application is a logical group of COM+ com ponents

Com ponents usually share an application if they depend on one another to accom plish their tasks and when all the com ponents require the sam e application level configuration, as with security or activation policy Com ponents in t he sam e application are often developed by the sam e team , and are m eant to be deployed

together

You can see all the COM+ applications installed on your m achine by opening the Com ponent Services Explorer and expanding the

Com puters folder in the Tree window: Com puters My Com puter

COM+ Applications Every icon in the COM+ Applications folder

represents a COM+ application Each COM+ application contains COM+ com ponents Com ponents m ust be explicitly im ported into the Com ponent Services Explorer to take advantage of COM+

services

The Com ponent Services Explorer offers a hierarchical approach to

m anaging COM+ services and configurations: a com puter contains

applications, and an application contains com ponents A com ponent has interfaces, and an interface has m ethods Each item in the

hierarchy has its own configurable properties Note that the

hierarchy allows you to view the param eters of any m ethod listed in the hierarchy

Figure 1 - 1 The Com ponent Services Explorer

1 3 Hello COM+

The best way to becom e acquainted with the Com ponent Services Explorer and basic COM+ term inology is to do a trivial exam ple This section walks you through the COM+ equivalent of the

canonical "Hello World" program You will build a COM+ application containing a COM com ponent that displays a m essage box saying

"Hello COM+ "

When developing your "Hello COM+ " application, follow these steps:

1 Create a classic COM com ponent All COM+ com ponents start their life as classic COM com ponents, developed with such tools as ATL, MFC, or Visual Basic 6.0

2 Create a new COM+ application to host the com ponent

3 Add the com ponent to the application

4 Write a client and test the com ponent

The rest of this chapter uses this "Hello COM+ " exam ple to

dem onstrate various COM+ features and capabilities The exam ple

is also available as part of the source files provided with this book ( see the Preface for inform ation on how to access these files)

1 3 1 Building a COM Com ponent

We will use ATL 7.0 to generate a classic COM com ponent, although you can also do it in Visual Basic 6.0 wit h alm ost the sam e ease Start a new ATL project in Visual Studio.NET and nam e it Hello For sim plicity, do not use Attributed project ( deselect Attributed in t he ATL Project Wizard under Application Settings) Also, do not select COM+ 1.0 support This selection adds a few interfaces explained in subsequent chapters that are not relevant to this exam ple Bring up the Add Class dialog ATL and select the Sim ple ATL Object item This step should bring up the ATL Sim ple Object Wizard dialog ( see Figure 1-2) Type the following entries, in order:

1 I n the Short Nam e field, enter Message

2 I n the CoClass field, enter Hello

Your com pleted dialog should look like Figure 1-2 There is no need

to access the Options selection in the dialog ( just use the defaults) Click OK when you’re done

Figure 1 - 2 Use the ATL object w izard to generate a sim ple COM object

Right- click t he I Message interface icon in the Class View, and select Add and then Add Method from the pop- up context m enu This step brings up the Add Method Wizard Enter ShowMessage as the

m ethod nam e and click OK

After following these steps, the ATL Object Wizard will generate a new interface definition in t he project I DL file, and t he new m ethod wizard will add a m ethod to that interface Verify that the interface definition in the I DL file looks like this:

Next, go to the m essage.cpp file and im plem ent the ShowMessage( )

m ethod of the CMessage class:

STDMETHODIMP CMessage::ShowMessage( )

{

::MessageBox(::GetActiveWindow( ),"Hello COM+","First COM+ Application",MB_OK);

return S_OK;

}

You can now com pile and build the DLL Every COM+ com ponent

m ust reside in a DLL, and that DLL m ust contain a type library

em bedded in it as a resource ATL will com pile and build the DLL for you and add a reference to the type library in the project resource

file, the hello.rc file COM+ does not require you to register your

com ponent, although the ATL build process will register it for you

As you will see later, COM+ m aintains its own com ponents

registration and configuration repository

1 3 2 Creating a COM+ Application

Open the Com ponent Services Explorer and expand My Com puter

COM+ Applications folder Right- click the COM+ Applications

folder and select New Application from the pop- up context m enu This step brings up the Application I nst all Wizard Click Next on the first wizard screen

I n the next wizard screen, select the Create an Em pty Application option in t he next wizard screen Now the wizard will let you specify the new application nam e and its application type, which can be either a library or a server type ( see Figure 1- 3) Enter Hello COM+ for the application nam e, and change the application type from the

default Server application to Library application A library

application indicates that the com ponents in the application will be

loaded directly in the process of their clients ( like a classic COM

in-proc server) A server application indicates that the com ponents will

run in their own process ( sim ilar to a classic COM local server) You can always change the application nam e and its activation t ype later with the Com ponent Services Explorer Click Next and Finish in the last wizard screen You have just created your first COM+

application

Figure 1 - 3 N am ing your new COM+ applicat ion and configuring it t o be a

library or a server applicat ion

I f you exam ine the Applications folder now, you will see your Hello

COM+ application Right- click its icon and select Properties from the

pop- up context m enu The application’s properties page— a

collection of tabs that let you configure the application— will now appear I n fact, every item in the Com ponent Services Explorer ( applications, com ponents, interfaces, m ethods, roles, and

subscriptions) has a properties page accessible in the sam e way ( by selecting Properties on the item 's context m enu or the properties button on the Com ponent Services Explorer toolbar) The Hello COM+ application's properties page is shown in Figure 1- 4 The General tab contains the application nam e, which you can change here if you'd like, and a description field The description field is a useful place to put a few sentences docum enting the application's purpose, its owner, etc Each COM+ application is uniquely

identified by a GUI D, called the Application I D, shown at the bottom

of the General tab You will alm ost never use the Application I D directly, but COM+ uses it internally

Figure 1 - 4 The applicat ion propert ies page

Other tabs on the application properties page let you configure the application act ivation m ode, support for queued com ponents,

security settings, and idle- tim e m anagem ent Later chapters

describe these application- level configurations in depth

Close the properties page and exam ine the application’s

Com ponents folder As you m ight expect, it is em pty now You will

now add a new com ponent to this application

1 3 3 Adding a Com ponent t o a COM+ Application

You can add a new com ponent to your application ( not surprisingly)

by using another wizard Right- click the Com ponents folder, select

New from the pop- up context m enu, and click Com ponent The Com ponent I nstall Wizard will now appear Click Next on the first screen On the next screen, select I nstall New Com ponent from the three choices The wizard will open a standard file- open dialog box

Look for the folder where you built hello.dll and select it The wizard

will present you with all the com ponents it could find in the specified

DLL I n the case of hello.dll, the wizard shows only the single

com ponent contained in it ( see Figure 1- 5) The wizard actually loads the em bedded type library in the DLL and looks for CoClass definitions You can use the Add button to specify additional DLLs Note that all t he com ponents in t he selected DLL will be added I f you want to add just a subset of them , you m ust add them all first and then rem ove the ones that do not belong in the applicat ion

m anually Click Next, and then click Finish in the last wizard screen Your com ponent is now part of the Hello COM+ application

Avoid using the "I m port com ponent( s) that are already registered" option in the Com ponent I nstall Wizard This option has a bug and will not retrieve inform ation about t he com ponent( s) interfaces

You will not see the com ponent( s) interfaces and

m ethods in the Com ponent Services Explorer and will not be able to configure them

Figure 1 - 5 The Com ponent I nst all W izard

Because type inform ation is em bedded in t he DLL, COM+ knows about your com ponent’s interfaces and m ethods You can expand

the I nterfaces and Methods folders ( under the Hello.Message

com ponent) to verify that COM+ has im ported the com ponent

correctly As shown in Figure 1-6, the IMessage interface and the ShowMessage m ethod were both im ported

Figure 1 - 6 The Hello COM+ applicat ion and its contained com ponent

The I nterfaces folder contains one entry for each interface your

com ponent supports The interfaces on the CoClass definit ion in t he

type library determ ine the num ber of entries The Methods folder

contains one item for each m ethod in t hat interface, again based on the interface definition in the type library

1 3 4 W riting a Test Client

Clients can create the com ponent using the class I D CLSID_Hello( C+ + ) or Hello ( Visual Basic 6.0) Although the com ponent is now

a COM+ com ponent and is part of a COM+ application, the side code is the sam e as if the com ponent were still a classic COM com ponent To prove this point ( and test your com ponent) , write a short C+ + client , such as the code in Exam ple 1- 1

client-Exam ple 1 - 1 A sim ple COM + client

#import "Hello.dll" no_namespace named_guids

::CoInitialize(NULL);

HRESULT hres = S_OK;

IMessage* pMessage = NULL;

hres = ::CoCreateInstance(CLSID_Hello,NULL,CLSCTX_ALL,

Dim obj As Hello

Set obj = New Hello

obj.ShowMessage

set obj = Nothing

Visual Basic 6.0 clients can also create the object using its prog- I D

I n that case, the type- library is not required ( at the expense of type- safety):

Dim obj As Object

Set obj = CreateObject("Hello.Message.1")

obj.ShowMessage

set obj = Nothing

Because the client side rem ains constant, regardless of the

com ponent configuration and application type, COM+ helps

decouple the client from the server This point is discussed in depth

in t he next chapter

1 4 COM+ Configured Com ponents

COM+ allows you to im port only in- proc ( DLL) com ponents You cannot im port COM com ponents that reside in a local server ( EXE) ; COM+ lets you configure the activation type of your application, server, or library I n the case of a library, the client sim ply loads the original DLL into its process and uses the com ponent I f you

configure the application to be a server application, COM+ prom otes your original DLL to becom e a local server by hosting it in a

surrogate process of its own However, COM+ cannot m ake a library application out of a COM local server I n addition, m any COM+ services require explicit process- level adm inistration t hat the local server’s code sim ply does not contain

Once an in- proc com ponent is im ported to COM+ , it is called a

configured com ponent to em phasize the fact that m uch com ponent

functionality and behavior is actually configured and adm inistered outside the com ponent A classic COM com ponent ( be it in- proc or local) that has not been im ported into COM+ is called a

nonconfigured com ponent Configured and nonconfigured

com ponents can interact freely and call each other’s interfaces The configured com ponent m ust reside on a Windows 2000 m achine, but the client of a configured com ponent can reside on any

Windows- fam ily m achine, such as Windows NT, Windows Me, or Windows 9x

Configuration lets you control the way your application, com ponent, interface, or m ethod behaves under COM+ The COM+ developm ent paradigm lets COM+ m anage as m uch of the nonbusiness logic plum bing as possible by declaring what services you want t o use Doing so lets you focus on the dom ain problem you are trying to solve and add business value instead of plum bing code to your product

Your configured com ponent’s interfaces can be dual, dispatch, or custom interfaces I f you use autom ation- com pliant interfaces, you

do not need to provide COM+ with a proxy/ stub DLL ( see COM

I nterface Types for m ore inform ation)

COM I nterface Types

I n general, there are two kinds of COM interface types:

autom ation- com pliant interfaces and custom interfaces

Contrary to com m on conceptions, an autom ation- com pliant

interface does not have to derive from I Dispatch or have all

the param eters be variants or variants- com patible types

( such as a BSTR or long) An autom at ion- com pliant interface

m ust have one of the following two directives in its

definition: dual or oleautom ation For exam ple:

COM can m arshal an autom ation- com pliant interface by

creating the appropriate proxy and stub autom at ically at

runtim e However, autom at ion- com pliant interfaces do have

lim itations on param eter types; for exam ple, they cannot

have as m ethod param eters structs wit h pointers in them

For ult im ate flexibility, you can use cust om interfaces These

interfaces do not have dual or oleautom ation in t heir

interface definition, and it is the developer’s responsibility t o

provide a proxy and a stub DLL

However, if your design calls for custom interfaces, you should provide COM+ with a proxy/ stub DLL that was built using the MI DL switch /Oicf to enable type library m arshaling I n any case,

configured com ponents cannot use interfaces that require custom

m arshaling You can develop configured com ponents in C+ + , Visual Basic, or even C# , since one of the core principles of COM,

language independence, is m aintained in COM+

You m ay be wondering by now, where does COM+ store the

configuration inform ation for all your applications and com ponents? Unlike classic COM, COM+ does not use the Windows registry

COM+ uses a dedicated repository called the COM+ catalog No

form al Microsoft docum entat ion of the exact physical location of the catalog exists, sim ply because it is not useful to you The only bit of configuration inform ation still stored in the Windows registry is the com ponent threading m odel and rem aining classic COM inform ation ( such as InprocServer32 and prog-ID registry keys)

1 5 Applications, DLLs, and Com ponents

COM+ applications are logical packaging units; DLLs, however, are physical packaging unit s There is no correlation between logical and physical packaging The only requirem ent is t hat a configured com ponent m ust belong to exactly one COM+ application; it cannot belong to m ore than one, and it m ust belong to at least one to take advantage of COM+ com ponent services As dem onstrated in Figure 1- 8, a COM+ application can host com ponents from one or m ult iple DLLs ( Application 2 has com ponents from two DLLs) I t is also

possible that not all the com ponents in a DLL are hosted in COM+ applications ( such as com ponent E) , and one DLL can contribute com ponents to m ult iple COM+ applications ( DLL 1 contributes

com ponents to Application 1 and Application 2)

Figure 1 - 8 COM+ applications and DLLs

The separation of physical from logical packaging gives you great flexibility in designing your application’s layout All the com ponents

in t he sam e COM+ application share the sam e application- level configuration set tings, regardless of their underlying DLL packaging However, I recom m end that you avoid installing com ponents from the sam e DLL into m ore than one application, such as com ponents

B and C in Figure 1- 8 The reason is that com ponents in the sam e application are assum ed to operate tightly together and trust each other On the other hand, nothing is assum ed about com ponents from different applications By placing com ponents from the sam e DLL into m ultiple applications, you m ay introduce needless security checks You m ight also introduce cross-process m arshaling

overhead, if those com ponents need one another to operate, which

is probably why they were put in the sam e DLL in the first place The COM+ Com ponent I nstall Wizard also does not handle

com ponents from the sam e DLL in m ultiple applications very well When you use the wizard to add com ponents from a DLL to an application, the wizard tries to add all com ponents in the DLL to the application I f som e of the com ponents are already part of other applications, the wizard will treat this situation as an error since it

will think you are trying to include a com ponent in m ore than one application

The bottom line is t hat you should put all com ponents t hat

cooperate closely or perform related functionality into a single

application Those com ponents can be written by m ultiple

developers and be contained in m ultiple DLLs, but they will

ult im ately share the sam e application configuration and be deployed together

1 6 Configuring COM+ Applications

The prim ary benefit of using COM+ is t hat you can configure a

com ponent or the application containing it without changing any code on the object or the client side This advantage enables you to focus your object code on its intended purpose, relying on the

various services COM+ provides instead of having to develop them yourself This section shows you how to configure som e of the

application- level options for the Hello COM+ program you created

1 6 1 COM+ Application Types

As m ent ioned previously, the application activation type ( a server or

a library application) is a configurable application- level attribute

called activation You can configure the application’s activation type

in t he application’s properties page, under the Activation tab ( see Figure 1-9)

Figure 1 - 9 Applicat ion Activat ion t ab

Changing the application type has significant im plications for m ost COM+ services The application type is a design- tim e decision that should consider the security needs of your com ponents, the calling patterns of your clients, fault isolation ( a server application gets its

own process) , and specific COM+ services requirem ents

Throughout the book, a particular service configuration that is

related to the activation type is pointed out explicitly However, even without knowing m uch about COM+ , you can use the following rule to decide on your activation type: prefer server type

applications, unless you absolutely need to run in the client process for perform ance reasons Library applications have som e lim itations

in using COM+ services ( such as securit y and queued com ponent support) , and they cannot be accessed from another m achine

1 6 2 COM+ Surrogate Processes

I f the original COM com ponents resided in a DLL, how does COM+ achieve different activation m odes for the configured com ponents? When the application is configured as a library, the client loads the DLL directly into its process When the application is configured as a server application, COM+ creates a surrogate process for it, called

dllhost.exe, that loads the DLL COM+ t hen places a proxy in the

client process and a stub in the surrogate process to connect the client to the object You can have m ultiple instances of the dllhost process running on your m achine sim ultaneously; if clients have created objects from different server applications, each server

application gets its own instance of dllhost

To verify these points yourself, configure the Hello COM+ exam ple

to run as a server application Run the t est client again, create the object, and call t he ShowMessage( ) m ethod, but do not press the

OK button The Com ponent Services Explorer gives you visual

feedback when a server application is running: the application icon and the active com ponents will be spinning Library applications will have no visual feedback when they are running in a client process, even if that process is anot her COM+ server application Expand the

COM+ Applications folder and select the Stat us View on the

Com ponent Services Explorer toolbar ( the button at the far right end of the toolbar; see Figure 1- 10) The Com ponent Services

Explorer will display the process I D of t he running server

applications Record the process I D for t he Hello COM+ application Next, bring up Windows Task Manager and locate the process with a

m atching I D I ts im age nam e will be dllhost.exe

Figure 1 - 1 0 Exam ining a running server applicat ion

The first CoCreateInstance( ) request for a com ponent in a server application creates a new dllhost process, to host com ponents from that applicat ion only Subsequent CoCreateInstance( ) calls to objects from the sam e application create new objects in the existing dllhost instance Unlike classic COM, there is no way to create each object in its own process No COM+ equivalent to the COM call you

m ake to CoRegisterClassObject( REGCLS_SINGLEUSE )

exists

The Com ponent Services Explorer also lets you m anage server application act ivation adm inistratively You can shut down a running application by right- clicking on it s icon in the Com ponent Services Explorer and selecting Shutdown from t he pop- up context m enu You can shut it down even when clients are holding active

references to objects in the application ( You shut down applications this way frequently during debugging sessions.) The Com ponent Services Explorer does not provide a way to shut down library

applications, since COM+ m ay not even m anage their client process You can also select Start from the server application pop- up context

m enu to launch a new dllhost process associated with that

application However, no objects will be created unless you use object pooling, which is discussed in Chapter 3

1 6 3 I dle Tim e M anagem ent

Another distinction between a classic COM local server and a COM+ server application is process shutdown I n classic COM, when the last client has released its last reference on an object in t he

process, COM would shut down that process COM+ provides idle tim e m anagem ent for COM+ server applications COM+ server

applications can be left running indefinitely even when idle (when there are no external clients) , or you can have COM+ shut them down after a predeterm ined tim eout This shutdown is done for the sake of perform ance I m agine a sit uat ion in which a client creates

an object from a server application every 2 m inutes on average, uses it for 1 m inute and 55 seconds, and then releases it Under classic COM, you would pay an unnecessary perform ance penalty

for creating and destroying the server process Under COM+ , you can configure the server application to be left running when idle for

a specific tim e I f during that tim e no client request for creating a new object has com e through, COM+ is allowed to shut down the process to release its resources I n this exam ple, you would

perhaps configure the server application to be left running when idle for 3 m inutes, as you would want to com pensate for variances in the client calling pattern I f a new call com es in wit hin those 3

m inutes, COM+ zeros the idle tim e counter and starts it up when the application is idle again You can configure server application idle tim e m anagem ent under the Advanced tab on the server’s properties page ( see Figure 1- 11) Library applications do not have

an idle tim e m anagem ent option and will be unloaded from their client process once the last object has been released

Figure 1 - 1 1 Configuring server applicat ion idle tim e m anagem ent

1 7 Debugging COM+ Applications

Debugging a COM+ application, be it a library or a server

application, is not m uch different from debugging an in- proc COM object or a local server A library application has the clear

advantage of allowing you to step through your code directly from the test client , since a library and a server application share the sam e process A server application always runs in a different

process than your test client and, t herefore, in a different debug

session ( a different instance of Visual Studio is at tached to that process) When debugging the business logic part of your

application, you m ay find it useful to debug it as a library

application, even if the design calls for a server application When debugging a library application, you m ay also need to point Visual Studio to t he exact location of t he com ponent’s DLLs This step is required so you can set breakpoints in t he com ponent’s code

When debugging a com ponent in a server application, you can step into t he com ponent’s code from the test client side in two ways First, you can start the client project in the debugger, break at a line where you call a m ethod on a com ponent in the server

application, and sim ply step into it ( F11 in Visual C+ + or F8 in

Visual Basic) This process launches a new instance of the debugger and attaches it to the running dllhost containing your com ponent You can then step through your com ponent’s code Second, you can attach a debugger to a server application by configuring it t o launch

in a debugger On the server application properties page, under the Advanced tab, there is t he Debugging properties group I f you

check the Launch in debugger checkbox ( see Figure 1-12) , when the first request for creating an object from that application com es

in, COM+ launches the application in a Visual C+ + debugger

session You m ay use this option often to track bugs in the

constructors of com ponents or bugs that do not happen in t he scope

of a client call COM+ is able to attach the debugger to the

application using a com m and- line option for Visual Studio When you launch the debugger with an executable filenam e as a

param eter, the debugger starts a debug session and creates the specified process ( in COM+ ’s case, always dllhost) COM+ also

specifies the server application I D as a com m and line param eter for dllhost:

msdev.exe dllhost.exe

1 8 Deploying COM+ Applications

Once you have tested your COM+ application and configured all the COM+ services to your liking, you need to install your application on

a custom er/ client m achine The Com ponent Services Explorer can generate a special file that captures all your application com ponents and settings This file is a Windows I nstaller ( MSI ) file, identified by

the m si file extension Clicking on an MSI file launches the

Windows I nstaller and installs the application with all its COM+ configuration param eters There is a one- to- one relationship

between an application and an MSI file Thus, if you have m ult iple applications in your product, you m ust generate one MSI file for each application

To generate the MSI file, right- click on your application icon in the Com ponent Services Explorer and select Export from the pop- up context m enu This action should bring up the Application Export Wizard Click Next t o go to the second wizard screen, where you are requested to enter the nam e and location for the application export file to be created ( see Figure 1- 13) Next, you should decide how to export the application: as a Server applicat ion or as an Application proxy ( see Figure 1- 13) Click Next and then click Finish on the next Wizard screen

Figure 1 - 1 3 Export ing a COM+ applicat ion

1 8 1 Proxy COM+ Applications

The nam es Server application and Application proxy are confusing

A "Server application" export is relevant for both library and server applications I t m eans that t he application will include in the MSI file the COM objects them selves, their settings, and their proxy/ stub DLLs ( if required) , and will install all on the server m achine

An "Applicat ion proxy" export installs on the client m achine only the type inform ation in the MSI it creates ( as well as the proxy/ stub DLLs, if required) The generated file does not have to include the com ponents them selves ( unless the type inform ation is em bedded

in t he com ponents, in which case the com ponents are only used as containers and are not registered) You can use a proxy installation when you want to enable rem ote access from a client m achine to the m achine where the application actually resides A proxy export

is available only for a COM+ server application, not for a library application

When you install a server export on another m achine, it will install the com ponents for local act ivation CoCreateInstance( ) requests create the objects locally— in the client process, if it is a library application, or in a dllhost process, if it is a server application When you install a proxy export, activation requests on that

m achine will be redirected to another rem ote m achine I n a way, a proxy export installed on a client m achine is a t hird kind of COM+

application This kind is usually called a proxy application You can

configure the proxy application to access any rem ote m achine on the network where the server application is installed, not just the

m achine that generated the proxy export You specify the "real" application location on the proxy application properties page under the Activation tab

A proxy application can even be installed on m achines running Windows NT or Windows 9x with DCOM, provided those m achines have Windows I nstaller installed on them Because the Windows

I nstaller cannot use the COM+ catalog t o store the proxy

application inform ation on a non- Windows 2000 m achine, it will use the registry and will store only the subset of inform at ion required for DCOM there Windows I nstaller is not com m only found on non-Windows 2000 m achines To m ake sure clients on those m achines are able to access your COM+ applications, you should incorporate the Windows I nstaller installat ion in your product installation The

Windows I nstaller installation file is called instm si.exe and is

available as part of the Developers Platform SDK

A proxy application cannot export another MSI file I n fact, all the application- com ponent, interface, and m ethod- level settings on a proxy application are disabled, except the Rem ote server nam e under the Activation tab The Rem ote server nam e edit box is

disabled in library and server applications

1 8 2 I nstalling and Uninst alling an Exported Applicat ion

The m ost com m on way to install an MSI file on another m achine is sim ply to click on it, which will launch t he Windows I nstaller The application files ( DLLs and proxy/ stubs) will be placed in a default location:

\Program Files\COMPlus Applications\{<the application’s

guid>}

I f you wish to have the application installed in a different location, you m ust use the Com ponent Services Explorer Application I nstall Wizard Bring up the wizard and select I nstall pre-built

application( s) Browse to where the MSI file is stored, and select it The wizard will let you choose whether you want to use the default location for installat ion or specify a different one

I f you want to autom ate uninstalling COM+ applications, you can use a com m and line instruction to invoke the Windows I nstaller to uninstall a COM+ application:

msiexec -x <application name>.msi

You can also use t he Windows Control Panel’s Add/ Rem ove

Program s applet to add or rem ove COM+ applications

1 9 Sum m ary

I n this chapter, you created a trivial exam ple COM com ponent and

im plem ented it in a DLL You used it as an in- proc server or as a local server and even controlled its life cycle and idle tim e

m anagem ent by configuring the com ponent ( actually its containing application) differently All this was achieved without changing a