net 2.0 interoperability recipes - a problem-solution approach (2006)

Here is the result when this code is executed:Result from AddSomeNumbers = 3 Press any key to exit If you prefer Visual Basic .NET, here is an example of calling the same unmanaged funct

.NET 2.0 Interoperability Recipes

A Problem-Solution Approach

Bruce Bukovics

.NET 2.0 Interoperability Recipes: A Problem-Solution Approach

Copyright © 2006 by Bruce Bukovics

All rights reserved No part of this work may be reproduced or transmitted in any form or by any means,electronic or mechanical, including photocopying, recording, or by any information storage or retrievalsystem, without the prior written permission of the copyright owner and the publisher

ISBN-13: 978-1-59059-669-2

ISBN-10: 1-59059-669-2

Printed and bound in the United States of America 9 8 7 6 5 4 3 2 1

Trademarked names may appear in this book Rather than use a trademark symbol with every occurrence

of a trademarked name, we use the names only in an editorial fashion and to the benefit of the trademarkowner, with no intention of infringement of the trademark

Lead Editor: Ewan Buckingham

Development Editor: Ralph Davis

Technical Reviewers: Christophe Nasarre, Nicholas Paldino

Editorial Board: Steve Anglin, Dan Appleman, Ewan Buckingham, Gary Cornell, Jason Gilmore,Jonathan Hassell, James Huddleston, Chris Mills, Matthew Moodie, Dominic Shakeshaft, Jim Sumser,Matt Wade

Project Manager: Sofia Marchant

Copy Edit Manager: Nicole LeClerc

Assistant Production Director: Kari Brooks-Copony

Production Editor: Ellie Fountain

Compositor: Kinetic Publishing Services, LLC

Proofreader: Elizabeth Berry

Indexer: John Collin

Cover Designer: Kurt Krames

Manufacturing Director: Tom Debolski

Distributed to the book trade worldwide by Springer-Verlag New York, Inc., 233 Spring Street, 6th Floor,New York, NY 10013 Phone 1-800-SPRINGER, fax 201-348-4505, e-mail orders-ny@springer-sbm.com, orvisit http://www.springeronline.com

For information on translations, please contact Apress directly at 2560 Ninth Street, Suite 219, Berkeley, CA

94710 Phone 510-549-5930, fax 510-549-5939, e-mail info@apress.com, or visit http://www.apress.com The information in this book is distributed on an “as is” basis, without warranty Although every precautionhas been taken in the preparation of this work, neither the author(s) nor Apress shall have any liability toany person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly

by the information contained in this work

The source code for this book is available to readers at http://www.apress.com in the Source Code section

For my son, Brennen

Contents at a Glance

About the Author xi

About the Technical Reviewers xiii

Acknowledgments xv

Introduction xvii

■ CHAPTER 1 Using C-Style APIs 1

■ CHAPTER 2 C-Style APIs: Structures, Classes, and Arrays 87

■ CHAPTER 3 Win32 API 141

■ CHAPTER 4 Using C++ Interop 191

■ CHAPTER 5 Using COM 235

■ CHAPTER 6 Exposing Managed Code to COM 327

■ CHAPTER 7 Marshaling to COM Clients 379

■ CHAPTER 8 COM+ Enterprise Services 441

■ CHAPTER 9 COM+ Enterprise Services Transactions 503

■ INDEX 583

v

About the Author xi

About the Technical Reviewers xiii

Acknowledgments xv

Introduction xvii

■ CHAPTER 1 Using C-Style APIs 1

1-1 Identifying the Unmanaged Function 2

1-2 Using the Function from Managed Code 5

1-3 Simplifying Reuse of Unmanaged Functions 8

1-4 Changing the Calling Convention 14

1-5 Renaming a Function 16

1-6 Changing the Character Set Used for Strings 21

1-7 Using Data Types That Improve Performance 25

1-8 Handling Errors from Unmanaged Functions 32

1-9 Using C++ Interop As a Managed Wrapper 41

1-10 Catching Unmanaged Exceptions with C++ Interop 50

1-11 Freeing Unmanaged Memory 58

1-12 Requesting Permission to Access Unmanaged Code 65

1-13 Securing Access to Unmanaged Code 72

1-14 Calling Functions Dynamically 83

■ CHAPTER 2 C-Style APIs: Structures, Classes, and Arrays 87

2-1 Passing Structures 88

2-2 Returning a Structure from Unmanaged Code 92

2-3 Specifying the Exact Layout of a Structure 97

2-4 Controlling Field-Level Marshaling Within Structures 104

2-5 Allocating Memory Within Structures 110

2-6 Passing Classes to Unmanaged Code 116

2-7 Passing Simple Arrays 126

2-8 Handling String Arrays 130

2-9 Passing Arrays of Structures 137

vii

■ CHAPTER 3 Win32 API 141

3-1 Accessing ANSI or Wide Functions 141

3-2 Retrieving the Win32 Error Code 147

3-3 Handling Callbacks 152

3-4 Using Windows Constants 156

3-5 Handling Handles 167

3-6 Passing Managed Objects 173

3-7 Marshaling Win32 Types 177

3-8 Replacing Win32 Calls with NET 179

■ CHAPTER 4 Using C++ Interop 191

4-1 Using C++ Classes 193

4-2 Mixing Managed and Unmanaged Code 199

4-3 Detecting Compile-Time Traits 205

4-4 Using Managed Objects from Unmanaged Code 209

4-5 Marshaling Strings 216

4-6 Marshaling Structures and Embedded Pointers 220

4-7 Handling Callbacks with C++ Interop 224

4-8 Using C++ As a Custom COM Wrapper 230

■ CHAPTER 5 Using COM 235

5-1 Using COM Components from NET 236

5-2 Importing a Type Library 242

5-3 Handling COM Events 248

5-4 Marshaling COM Data Types 256

5-5 Marshaling COM Variants 263

5-6 Marshaling COM Arrays 272

5-7 Extending COM Classes 281

5-8 Changing the Apartment Model 290

5-9 Refactoring for Performance 296

5-10 Creating a Late-Bound COM Object 298

5-11 Sharing an Interop Assembly 303

5-12 Deploying Your Application 306

5-13 Converting HRESULTs to Exceptions 308

5-14 Refactoring HRESULTs 314

5-15 Retrieving the HRESULT 319

5-16 Providing Additional Error Information 322

■C O N T E N T S

viii

■ CHAPTER 6 Exposing Managed Code to COM 327

6-1 Exposing NET Classes Using Late Binding 328

6-2 Exposing NET Classes Using Early Binding 332

6-3 Exposing NET Classes with Interfaces 338

6-4 Managing COM Identity 346

6-5 Controlling COM Visibility 353

6-6 Preparing Assemblies for COM Interop 361

6-7 Exposing Managed Events to COM 364

6-8 Providing HRESULTs for Exceptions 369

6-9 Preserving Success HRESULTs 374

■ CHAPTER 7 Marshaling to COM Clients 379

7-1 Controlling Parameter Direction 379

7-2 Marshaling Strings 392

7-3 Marshaling Arrays 402

7-4 Marshaling Variants 414

7-5 Marshaling Currency 418

7-6 Marshaling Null Variant Strings 423

7-7 Marshaling Classes and Structures 426

7-8 Passing Optional Parameters 436

■ CHAPTER 8 COM+ Enterprise Services 441

8-1 Exposing Managed Code to COM+ 442

8-2 Implementing a Server Application 448

8-3 Installing a Serviced Component 453

8-4 Registering Components Dynamically 456

8-5 Activating Components Just-in-Time 459

8-6 Using Object Pooling 467

8-7 Implementing Private Components 475

8-8 Using Role-Based Security 479

8-9 Performing Manual Security Checks 488

8-10 Writing Managed Queued Components 493

■C O N T E N T S ix

71faaa86f01e1350c2e3f80cf3a26d14

■ CHAPTER 9 COM+ Enterprise Services Transactions 503

9-1 Monitoring Transaction Status 504

9-2 Enabling Automatic Transactions 515

9-3 Placing an Automatic Vote 528

9-4 Placing a Manual Vote 535

9-5 Defining a Unit of Work 544

9-6 Controlling the Transaction Isolation Level 556

9-7 Implementing Transactional Code Blocks 558

9-8 Building Your Own Resource Manager 564

9-9 Using Services Without Components 577

■ INDEX 583

■C O N T E N T S

x

About the Author

■BRUCE BUKOVICShas been a working developer for over 25 years Over the last quarter-century

he has designed and developed applications in such widely varying areas as banking, corporate

finance, credit card processing, payroll processing, and retail automation

He has firsthand developer experience with C, C++, Delphi, Visual Basic, C#, and Java, androde the waves of technology as they drifted from mainframe to client/server to n-tier, from

COM to COM+, and from web services to NET Remoting and beyond

He considers himself a pragmatic programmer He doesn’t stand on formality and doesn’t

do things a certain way just because they have always been done that way He’s willing to look

at alternate or unorthodox solutions to a problem if that’s what it takes

Bruce is currently employed at Radiant Systems, Inc., in Alpharetta, Georgia, as a seniordeveloper and architect in the central technology group

xi

About the Technical Reviewers

■CHRISTOPHE NASARREis a software architect for Business Objects, a company that develops

desktop and web-based business intelligence solutions During his spare time, Christophe

writes articles for MSDN Magazine, MSDN/Longhorn, and ASP Today, and since 1996 he has

reviewed books on Win32, COM, MFC, and NET

■NICHOLAS PALDINOis a developer in the New York City area for Exis Consulting, Inc., a

bou-tique software provider that offers software solutions in the fixed income space Nicholas has

also been awarded the Microsoft MVP award for the past four years for his frequent

contribu-tions in the microsoft.public.dotnet.languages.csharp newsgroup, where he submits anywhere

between 100 and 500 posts a month He also provides technical review services for a number

of publishers

xiii

First of all, I’d like to thank the entire team at Apress You all worked very hard to make this

book a reality Thank you for an exceptional job and for making the process a smooth one Special

thanks go to Ewan Buckingham, who was my editor at Apress, and to Sofia Marchant, who kept

things organized and on track Thanks also go to Nicole LeClerc and Ellie Fountain for a great job

copy editing and production editing, respectively, and for being so easy to work with

I would especially like to thank Ralph Davis, who took on the role of development editorfor the book Ralph did a fantastic job handling this first-time author Not only was he there to

correct my mistakes, but also he questioned things that weren’t clear and encouraged me to

improve things that were Ralph was my sounding board and voice of reason

I would also like to thank my technical reviewers, Christophe Nasarre and Nicholas Paldino,who both did an amazing job Their comments and suggestions helped to improve the accuracy

and clarity of all of the recipes Their efforts and attention to detail made this a much better book

Thanks also go to John Osborn for believing in the initial idea for this book and championing it

Finally, I’d like to thank my loving wife, Teresa, and son, Brennen, for being patient with mewhen I was working late, for understanding when I said I was busy, and for encouraging me when

things didn’t always go as planned I love both of you very much Brennen, I have time to play

that game of chess now

xv

It is difficult or impossible to immediately throw out all existing code and start over when

a new technology arrives That’s the situation with Microsoft NET It represents a new and

improved way of developing software for the Windows platform And, given the chance, you

would likely love to rewrite all of your existing code in the newer managed code environment

that NET provides

However, you have that little problem known as legacy code You may have C libraries,C++ class libraries, Visual Basic 6.0 COM components, or ATL COM components that you rely

upon to run your applications You may be using third-party libraries and COM components

that represent a significant investment You can’t simply throw all of that away Instead, you

need to find a way to move forward with new NET development while reusing existing pieces

of tested, working code You need a way to interoperate with the existing code until you have

a chance to finally rewrite all of it in NET (if ever)

Fortunately, Microsoft NET provides a rich set of tools that allow you to do just that Thesetools simplify the transition to an all-.NET environment, allowing you to replace a component

here and a component there The problem is that sometimes those tools are difficult to

under-stand and use And in many cases, Microsoft has provided more than one way to accomplish

a particular interop task Finding the appropriate tool for the task at hand can sometimes be

This book is appropriate for any NET developer who needs to interoperate between NET code

and non-.NET Windows code You may be an experienced NET developer who has never had

the need to interoperate with native code before Or you may be completely new to NET and

are just learning the languages and class libraries associated with NET In either case, this book

is for you

Most of the examples in this book are presented in both C# and Visual Basic NET (VB.NET)

You will be able to understand the examples as long as you know one of these languages But

this book isn’t designed to teach you a language Likewise, you should already be familiar with the

basics of the NET Framework Class Library (FCL) You don’t have to be a guru, but you should

at least know the basics

Since the book is all about interop with existing code, the examples also typically use one

or more native Windows languages For example, the chapters covering the use of C-style

func-tions use examples written in native C++ code The chapter that focuses on the use of COM

xvii

components presents Visual Basic 6.0 (VB6) and C++ ATL example components that are used

by NET client code These same native languages are later used as client code when managedclasses are exposed to COM

While unmanaged code is used extensively in the examples, it is not the primary focus ofthis book So if you know VB6 but don’t know C++, that’s OK—you’ll still benefit from the exam-ples Most of the NET code works the same way regardless of the unmanaged language used

If there are differences, they are noted in the examples

Likewise, the chapters covering COM and COM+ assume that you are already familiarwith these technologies This is not a book about learning COM and COM+, but it will showyou how to use COM and COM+ from NET

How This Book Is Organized

This book is organized into nine chapters, with each one focusing on a different aspect ofWindows interoperability The following sections provide a brief summary of the contents of eachchapter

Chapter 1: Using C-Style APIs

This chapter discusses the use of Platform Invocation Services (PInvoke) to access C-stylefunctions from managed NET code It includes recipes that demonstrate how to declare anduse unmanaged functions, change the calling convention and character set, handle errors andexceptions, and manage memory

Chapter 2: C-Style APIs: Structures, Classes, and Arrays

This chapter is a logical continuation of Chapter 1 and covers topics that relate to user-definedtypes such as structures and classes Recipes in this chapter cover passing structures, classes,and arrays between managed and unmanaged code; controlling the field alignment within

a structure; and implementing field-level marshaling within a structure

Chapter 3: Win32 API

This chapter covers the topics associated with using Win32 functions from managed NETcode Recipes include accessing the ANSI or Unicode version of a function, retrieving Win32error codes, handling callbacks, and passing handles and objects between managed andunmanaged code The chapter also provides a recipe that illustrates how to replace a set ofWin32 functions entirely with managed code

Chapter 4: Using C++ Interop

The focus of this chapter is on using C++ to solve various interop problems Recipes in thischapter include how to mix managed and unmanaged code in a project and within a singlesource file, how to use managed objects from unmanaged code, and how to marshal stringsand structures with embedded pointers and callbacks There is also a recipe that demonstratesthe use of C++ as a custom COM wrapper

■I N T R O D U C T I O N

xviii

Chapter 5: Using COM

All of the recipes in this chapter demonstrate some aspect of using COM components from

managed NET code Recipes include importing and using a COM object, handling COM events,

marshaling common COM data types, handling HRESULT codes, and providing error information

Chapter 6: Exposing Managed Code to COM

The recipes in this chapter are the reciprocal of Chapter 5 They show you how to expose

managed NET code as COM components, suitable for use by any COM client Recipes

include exposing managed components to COM by defining your own interface, controlling

COM identity and visibility, exposing managed events to COM, and handling HRESULT codes

and managed exceptions

Chapter 7: Marshaling to COM Clients

This chapter continues where Chapter 6 left off, focusing on a set of specific COM marshaling

problems Recipes include how to control parameter direction; how to marshal strings, arrays,

Variants, and currency; and how to marshal classes and structures to COM clients

Chapter 8: COM+ Enterprise Services

This chapter shows you how to make use of COM+ services from managed code Recipes include

developing a COM+ component in managed code, installing and registering the component,

using just-in-time (JIT) activation, using object pooling, implementing role-based COM+

security, and writing Queued Components

Chapter 9: COM+ Enterprise Services Transactions

The recipes in this chapter all focus on the use of COM+ transactions The recipes demonstrate

how to enable transactions, how to place a vote for a transaction, how to use the new NET

Framework 2.0 transactional code blocks, how to build your own resource manager, and how

to use services without components

Software Requirements

To run the examples in this book, you need some way to build and run C# or VB.NET code

The bare minimum for this is the NET Framework SDK and a source code editor While this

minimal setup allows you to run the example code, many of the recipes show you how to use

features of Visual Studio NET 2005 to simplify the job of interop Therefore, use of Visual

Studio NET 2005 is highly recommended

All of the code in this book was originally developed using beta 2 and release candidate 1

of Visual Studio NET 2005 It was subsequently checked using the final release to

manufactur-ing (RTM) version

All of the C++ unmanaged code used in the examples can be built with Visual Studio NET

2005 You don’t need the older 6.0 version of Visual C++ for this purpose However, many of the

COM examples use VB6 Since VB6 is a drastically different language than VB.NET, you’ll need

VB6 to build and run those examples

■I N T R O D U C T I O N xix

Using C-Style APIs

Platform Invocation Services (PInvoke or P/Invoke) is the part of the common language

runtime (CLR) that enables managed NET code to access unmanaged functions The functions

can be written in ordinary C or C++, and they are usually packaged as dynamic link libraries

(DLLs) These are the same unmanaged functions that you know and love, as they are routinely

used by your non-.NET applications to provide core business functionality PInvoke allows you

to reuse the functions you need now while you contemplate a future rewrite in a NET language

When boiled down to only the essential elements, the steps to using PInvoke to accessunmanaged functions are as follows:

1. Identify the function that you need to call

2. Declare the function in managed code and apply the attributes that PInvoke uses

3. Call the function

This is the essence of PInvoke, but along the way there will likely be several twists and turns

The complexity of PInvoke is directly related to the complexity of the unmanaged function you

need to call

If you are using Visual C++, you have a second option available to you for accessing aged functions, one that no other NET language supports It’s simply called C++ Interop This C++

unman-technology was previously called It Just Works, or IJW It enables you to make calls to unmanaged

code without the special function declarations or attributes required by PInvoke in other languages

Interop marshaling (or just marshaling) is the process of passing data between managed

and unmanaged memory during a call Marshaling takes place when input parameters are passed

to an unmanaged function, and when a result is returned from the call Tasks performed by the

marshaler include conversion of data between managed and unmanaged types, copying of

the converted data between managed and unmanaged memory, and freeing memory at the

conclusion of the call

Most of the PInvoke classes and attributes can be found in the System.Runtime

InteropServicesnamespace The documentation for this namespace is a good starting point

when you are searching for just the right attribute or class for the task at hand

This chapter focuses on the core topics related to the use of unmanaged functions frommanaged code There are recipes that cover the process of identifying the function to call, then

declaring and calling the function Several recipes discuss the use of managed wrappers to

encapsulate the unmanaged calls, with one version of a wrapper focusing on exception handling

and another on security

1

C H A P T E R 1

■ ■ ■

1 - 1 ■ I D E N T I F Y I N G T H E U N M A N A G E D F U N C T I O N

2

The performance implications of the data types used during interop are demonstrated inone recipe, while memory-management issues are discussed in another In between all of this,there are recipes that cover calling conventions, renaming of functions, error handling, andstring character-set issues

The chapter concludes with a recipe that demonstrates how to dynamically call a function

in a DLL

One common use of PInvoke is to call Win32 API functions The techniques described inthis chapter are applicable to calling Win32 functions or calling your own functions Additionalinformation on calling Win32 functions is provided in Chapter 3

1-1 Identifying the Unmanaged Function

Problem

You want to use an existing unmanaged function from managed code, and you think you’veidentified the DLL containing the function However, you need a way to verify the presenceand exact name of the function within the DLL

Solution

Use the dumpbin.exe command-line utility to view the functions that have been exported from

an unmanaged DLL This utility is included with Visual Studio NET as part of the Visual C++set of tools To run this utility against a DLL, follow these steps:

1. Open a Visual Studio NET command prompt You’ll find a shortcut to this commandprompt within the Visual Studio NET Program Files tree structure off the Start menu.Opening this command prompt sets up the environment variables needed to accessthe Visual Studio NET command-line tools

2. Change to the directory containing the DLL that you wish to examine

3. Execute the tool using a command in this format:

dumpbin /exports <dllname>

The output from this command lists the function names that have been exported fromthe named DLL You can then use this list to confirm the presence and entry point of the func-tion that you need to use

As an example, you can execute dumpbin on one of the DLLs provided by Microsoft, such

as kernel32.dll This DLL is located in the System32 folder where Windows was installed ThisDLL contains many of the Win32 functions, and the list of functions exported from it is very large

To see the exports from kernel32.dll, you execute this command:

dumpbin /exports kernel32.dll

When you execute this command, you’ll see a long scrolling list of functions If you prefer,you can redirect the output to a file, like this:

dumpbin /exports kernel32.dll > MyList.txt

1 - 1 ■ I D E N T I F Y I N G T H E U N M A N A G E D F U N C T I O N 3

A partial list of the output from this command follows

Dump of file kernel32.dll

File Type: DLL

Section contains the following exports for KERNEL32.dll

00000000 characteristics40B53BB8 time date stamp Wed May 26 20:52:08 20040.00 version

1 ordinal base

829 number of functions

829 number of namesordinal hint RVA name

The dumpbin utility has been included with Visual C++ for several releases now, including

Visual C++ 6.0 and Visual Studio NET 2003 and 2005 It is designed to display information

from a binary file that is in the 32-bit Common Object File Format (COFF) This can include

libraries of COFF objects, executable files, and DLLs

■ Note The dumpbinutility has a number of other command-line options, allowing you to further dissect

any COFF binary However, the /exportsoption works best for viewing functions that have been exported

from an unmanaged DLL Consult the MSDN documentation for the complete list of options

1 - 1 ■ I D E N T I F Y I N G T H E U N M A N A G E D F U N C T I O N

4

In general, in order to use an unmanaged function, you’ll need to identify a number ofitems related to the function, including the following:

• The entry point of the function itself

• The name of the DLL containing the function

• The signature of the function, including the number, type, and order of any callingarguments as well as any return value

• The calling convention of the function (i.e., StdCall, Cdecl)

• Memory management requirements (i.e., does the function allocate any memory thatyou are expected to free)

• Prerequisites for calling the function (i.e., do you need to first call other functions inorder to set up some internal state)

Some of these items may be readily available, while others may take some amount ofresearch on your part The dumpbin utility can assist you with some of that research, helpingyou to locate the correct dynamic link library that contains a particular function and to verifythe exact entry point name of the function (the first two items in the preceding list)

You may wonder why we need to verify the function name itself After all, shouldn’t thename of the function be obvious? You would think so, but that’s not always the case We need

to make an important distinction between the function name declared within the C or C++header file and the actual entry point that is exported from the DLL, since these are not alwaysthe same When calling a function from managed code, we are concerned with only the actualentry point name exported from the DLL

Many times, the header file will use a #define statement to provide a consistent alias namefor a number of function entry points, varying the actual entry point based on compile-timeoptions The Win32 API is notorious for this, exposing either the wide (Unicode) or ANSI version

of a function depending on your compile options An example of this is shown in the sampleoutput of this command, where you see AddAtomA and AddAtomW, the ANSI and Wide versions

of AddAtom When referencing this function from unmanaged C or C++ code, you’ll usually justrefer to AddAtom without the trailing letter The correct version is defined behind the scenesbased on your compile settings and preprocessor definitions (e.g., UNICODE) However, whenreferencing this function from managed code, you’ll need to specify the actual entry pointusing the full name shown in the dumpbin listing

Once we’ve identified the function entry point and DLL, we’re still left with the other items

in the list Unfortunately, we don’t have another utility that will help us with this research Ourbest source for answering the remaining questions is the header file that declares the unman-aged function and any available documentation The C or C++ header files can usually help usidentify the calling arguments We may also get lucky and find comments in the code that helpanswer the remaining questions

Related Information

See recipe 3-1 (Accessing ANSI or Wide Functions)

// A trivial unmanaged function that we want to call

// from managed code

int AddSomeNumbers(int numOne, int numTwo)

int AddSomeNumbers(int numOne, int numTwo);

An example of using this function from managed C# code follows

//declare the unmanaged api [DllImport("FlatAPILib.DLL")]

public static extern int AddSomeNumbers(

int myNumA, int myNumB);

Here is the result when this code is executed:

Result from AddSomeNumbers = 3

Press any key to exit

If you prefer Visual Basic NET, here is an example of calling the same unmanaged function:Imports System.Runtime.InteropServices 'needed for DllImport

Module VBClient

'declare the unmanaged function

<DllImport("FlatAPILib.dll")> _ Public Function AddSomeNumbers( _

ByVal numA As Integer, ByVal numB As Integer) _

As Integer End Function

Sub Main()Dim result As Integer = 0

'call the unmanaged function result = AddSomeNumbers(1, 2)

'show the resultsConsole.WriteLine( _String.Format("Result from function is {0}", result))Console.Read()

End SubEnd Module

The result from the Visual Basic NET code looks like this:

Result from function is 3

1 - 2 ■ U S I N G T H E F U N C T I O N F R O M M A N A G E D C O D E 7

How It Works

The DllImport attribute contains a number of optional properties that give you complete

con-trol over the way an unmanaged function is called Many of these properties are discussed in

other recipes in the first three chapters of this book The preceding example illustrates the bare

minimum that you’ll need and makes a number of assumptions

Any function that you call must be declared within your managed code That’s why theexample contains this declaration:

public static extern int AddSomeNumbers(int myNumA, int myNumB);

This allows other managed code to reference this function Note that we’ve declared thefunction with the extern modifier This tells the compiler that this function is implemented

externally and not to look for it within any managed code

In this example, we’ve also declared the function as static The compiler enforces thiswhenever the DllImport attribute is applied This makes sense, since the function we’re declar-

ing isn’t a method on an object instance

■ Note In Visual Basic NET, the Sharedkeyword is used to declare astaticfunction If you apply the

DllImportattribute to a function that is declared within a class, the function must be declared with

the Sharedkeyword However, notice that the Visual Basic NET example code shown here does not declare the

AddSomeNumbersfunction as Shared This works without the Sharedkeyword since the function is declared

within a Visual Basic NET module instead of a class

Immediately above the function declaration, we add the DllImport attribute:

the function that was exported from the DLL

In this example, we’ve declared the unmanaged function as extern "C" in the C header file

This prevents the C++ compiler from mangling or decorating the function name Since C++

allows function overloading, the compiler will normally use the function name, parameters,

and return value to generate a unique name for the function Declaring the function as extern

"C"suppresses this behavior and provides us with an exported function with the name that we

expect

Also note that the parameter names used in the unmanaged and managed code do notneed to match The only requirement is that the exact number, order, and type of parameters

match

1 - 3 ■ S I M P L I F Y I N G R E U S E O F U N M A N A G E D F U N C T I O N S

8

We haven’t specified a calling convention in the DllImport attribute, so the default of Winapi

is used This uses the default calling convention for the platform For most Windows platforms,this defaults to StdCall For Windows CE, the default is Cdecl The calling convention determinesthe order in which the parameters are passed and who cleans up the stack The only requirement

is that the calling convention specified in the DllImport attribute must match the conventionused in your unmanaged code

Once the function is declared, we can easily call it from our managed code as if it werejust another static method in our class

//make the unmanaged call

int result = AddSomeNumbers(1, 2);

Since we’ve declared this function as static within our managed code, we must call it as

a member of the class rather than an object instance We don’t need to do anything special totranslate the parameters or the return value between the managed and unmanaged code Inthis case, we’re dealing with only integers, which are represented the same way in both envi-ronments This won’t always be the case

man-Solution

One way to enable easier reuse of unmanaged code is to develop a managed wrapper class Thewrapper is easily used by other managed classes and completely hides the details of callingthe unmanaged function In fact, it completely hides the fact that you are calling an unmanagedfunction

Consider an example using this unmanaged function:

int GetCustomerStatus(char* customerId, int customerType)

{

//code to look up the customer and return//a status goes here

if (customerType == 2122){

return 1; //current}

1 - 3 ■ S I M P L I F Y I N G R E U S E O F U N M A N A G E D F U N C T I O N S 9

else if (strcmp(customerId, "bbbbbb") == 0){

return 3; //past due}

return 0;

}

While this certainly isn’t production-level code, the function implements just enough code

to demonstrate the use of a wrapper

The declaration of the function looks like this:

extern "C" declspec(dllexport)

int GetCustomerStatus(char* customerId, int customerType);

A C# managed wrapper for this function might look like this:

enum CustomerStatus{

Unknown = 0,Current = 1,Inactive = 2,PastDue = 3,InCollections = 4}

/// <summary>

/// Defines the type of customer and is used/// by the unmanaged function to determine/// the database to search

/// </summary>

enum CustomerType{

Individual = 1001,Corporate = 2122,Government = 35,NonProfit = 501}

public static extern int GetCustomerStatus(

String customerId, int customerType);

}/// <summary>

/// A managed wrapper for unmanaged customer functions/// </summary>

class CustomerWrapper{

//convert enum values to those expected//by the unmanaged function This eliminates//the need to pass magic numbers from//managed code We can validate the enum//prior to calling the function

int customerTypeInt = 0;

if (Enum.IsDefined(typeof(CustomerType), custType)){

customerTypeInt = (int)custType;

}else{throw new ArgumentOutOfRangeException(

String.Format(

"Invalid CustomerType {0}", custType));

}//make the function callint result = NativeMethods.GetCustomerStatus(

custId, customerTypeInt);

1 - 3 ■ S I M P L I F Y I N G R E U S E O F U N M A N A G E D F U N C T I O N S 11

//we convert the integer result to our enum//to make the result clearer to other managed code

if (Enum.IsDefined(typeof(CustomerStatus), result)){

return (CustomerStatus)result;

}else{return CustomerStatus.Unknown;

}}}}

A Visual Basic NET version of this wrapper could be implemented like this:

Imports System

Imports System.Runtime.InteropServices

'define enum for status

Public Enum CustomerStatus

Unknown = 0Current = 1Inactive = 2PastDue = 3InCollections = 4End Enum

'define enum for cust type

Public Enum CustomerType

Individual = 1001Corporate = 2122Government = 35NonProfit = 501End Enum

Friend Class NativeMethods

'declare the unmanaged api

<DllImport("FlatAPILib.DLL")> _Public Shared Function GetCustomerStatus( _ByVal customerId As String, _

ByVal customerType As Integer) As IntegerEnd Function

End Class

Public Class CustomerWrapperVB

'wrapper methodPublic Function GetCustomerStatus( _

1 - 3 ■ S I M P L I F Y I N G R E U S E O F U N M A N A G E D F U N C T I O N S

12

ByVal custType As CustomerType, _ByVal custId As String) As CustomerStatusDim customerTypeInt As Integer = 0'validate the enum value passed in

If (System.Enum.IsDefined( _GetType(CustomerType), custType)) ThencustomerTypeInt = custType

ElseThrow New ArgumentOutOfRangeException( _String.Format( _

"Invalid CustomerType {0}", custType))End If

'make the function callDim result As Integerresult = NativeMethods.GetCustomerStatus( _custId, customerTypeInt)

'convert the result

If (System.Enum.IsDefined( _GetType(CustomerStatus), result)) ThenReturn result

ElseReturn CustomerStatus.UnknownEnd If

End FunctionEnd Class

In this example, we’ve chosen to declare the unmanaged function in a separate classnamed NativeMethods This follows a Microsoft pattern that is checked by tools such as FxCop.Implementing things this way is certainly not a requirement However, it does provide a subtlereminder that the function being called is unmanaged code and is possibly unsafe

Code to execute the C# version of this wrapper looks like this:

CustomerWrapper wrapper = new CustomerWrapper();

//call the wrapper and show the result

CustomerStatus status = wrapper.GetCustomerStatus(

CustomerType.Corporate, "aaaaa");

Console.WriteLine(

"Result status is " + status.ToString());

//call the wrapper and show the result

1 - 3 ■ S I M P L I F Y I N G R E U S E O F U N M A N A G E D F U N C T I O N S 13

When this code is executed, we see these results:

Result status is Current

Result status is PastDue

How It Works

Developing a wrapper for unmanaged code allows you to hide the details of calling an

unman-aged function from other manunman-aged code Other manunman-aged classes simply create an instance of

your wrapper class and use it, without knowing or caring that it actually references an

unman-aged function

The idea of hiding low-level details using a wrapper isn’t a new concept However, this is

an especially important technique to use when dealing with unmanaged code The following

are some of the benefits of this approach:

• A wrapper isolates the interop code to a single class If the unmanaged function changes,you need to modify and test only the wrapper class The remainder of your managedcode isn’t affected

• A wrapper acts as a convenient place to logically group calls to related functions In manycases, you may need to make calls to multiple functions that work together when executed

in a prescribed sequence Placing all of the related functions in a single wrapper allowsyou to execute multiple functions during a single method call

• A wrapper provides you with a convenient place to normalize input and output parameters

This involves controlling the input/output parameters to and from the unmanagedfunction using enumerated types and type conversion logic This allows you to reducethe spread of any “magic numbers” used by the unmanaged code

• A wrapper provides a central place for memory-management code needed to call somefunctions The example function (GetCustomerStatus) doesn’t have any special memory-management requirements, but this won’t always be the case

• A wrapper can include any amount of validation prior to calling the unmanaged function

This is especially important when calling unmanaged functions that might be considereddangerous if passed incorrect values

• A wrapper provides a place to check unmanaged return codes and translate these intoresults that are more meaningful to your managed code This might include throwingexceptions when incorrect results are returned

• Most important, a wrapper provides a better migration path away from the unmanagedfunction Your other managed code is dependent on only the wrapper, not the unman-aged function As your needs change, you can replace the unmanaged function call withnew managed code called from the wrapper, without affecting the remainder of yourapplication

In the example wrapper, we’ve tried to control the input and output of the function by firstdefining enumerated types These types define any “magic numbers” used by the function

1 - 4 ■ C H A N G I N G T H E C A L L I N G C O N V E N T I O N

14

This greatly simplifies the use of this function for all other managed code It allows us to writecode that is much more descriptive and less error-prone For example, consider this code:if(status == CustomerStatus.PastDue)

or

if(status == 3)

Which code would you rather read? Which code is self-describing? Which code will beeasier to modify years from now once the original developer has moved on to greener pastures?The sample wrapper also uses an enumerated type for the custType input parameter Thisallows you to validate the input value against a set of named values, eliminating the chance ofpassing an invalid magic number to the function You won’t have to wonder if a corporate cus-tomer is a type 2122 or a 2123, because you’ll have an enum type that defines the acceptablevalues

extern "C" declspec(dllexport)

int cdecl AddSomeNumbers(int numOne, int numTwo);

To specify that this function should be invoked with the cdecl calling convention, youdeclare the function like this in C#:

[DllImport("FlatAPILib.DLL",

CallingConvention=CallingConvention.Cdecl)]

public static extern int AddSomeNumbers(int myNumA, int myNumB);

The same declaration in a Visual Basic NET module looks like this:

<DllImport("FlatAPILib.DLL", _

CallingConvention:=CallingConvention.Cdecl)> _Public Function AddSomeNumbers( _

ByVal myNumA As Integer, ByVal myNumB As Integer) _

As IntegerEnd Function

CE, the default is Cdecl.

How It Works

The calling convention is important since it defines part of the contract between the

unman-aged function and your manunman-aged code In particular, the calling convention determines the

party responsible for cleaning up the stack Table 1-1 summarizes the possible choices, as

defined in the CallingConvention enumeration

Table 1-1. CallingConvention Enumeration

Calling Convention Description

StdCall The callee (the unmanaged function) cleans up the stack Parameters are

pushed on the stack from right to left (reverse order)

Cdecl The caller (managed code) cleans up the stack Parameters are pushed on

the stack from right to left (reverse order) Since the caller performs thecleanup, this calling convention supports functions that accept a variablenumber of parameters

Winapi If this calling convention is specified, the default for the platform will be

used If run under Windows, StdCallwill be used However, if run underWindows CE NET (the NET Compact Framework), Cdeclwill be used

ThisCall This calling convention is primarily used for interop with C++ class

methods It passes a pointer to the C++ object as the first parameter Itwould not typically be used when calling flat functions

FastCall This calling convention makes an attempt to pass parameters in registers

whenever possible While this convention is available in the CallingConventionenumeration, it isn’t supported in NET Therefore, you will never use it inyour managed code

One other aspect to the calling convention is that it controls the way functions are named

as they are exported in unmanaged code This is referred to as name decoration.

For example, if a function is defined as stdcall and extern "C", it is decorated with

a leading underscore (_), and the function name is followed by the at sign (@) and the number

of bytes in the argument list (the total bytes of all parameters)

Using the AddSomeNumbers function shown in the example, the actual entry point for thefunction name would look something like this: _AddSomeNumbers@8 The magic number of 8 is

used because we’re passing two 4-byte integers, giving us a grand total of 8 This name can be

confirmed by running the dumpbin utility on the sample DLL

■ Note For additional error information during debugging, you can enable the Managed Debugging tants included with Visual Studio NET (by selecting Debug ➤ Exceptions) These agents provide lower-leveldetails as to the cause of the problem during a debug session.

Assis-The best way to determine the calling convention used by a function is to examine theC/C++ header file If there is no explicit calling convention specified for the function, it willdefault to the C/C++ project settings

If the source for the function isn’t available, or as a sanity check, you can examine thenames exported from the DLL using the dumpbin utility By viewing the names and knowingthe rules for decorated names, you should be able to determine the calling convention for

Solution

The DllImport attribute allows you to optionally specify the entry point name of an aged function When an entry point name is specified, that name will be matched to the entrypoint exported from the DLL You are then free to choose a different name of the function to

unman-be used by managed code

Consider the C declaration for this simple unmanaged function:

int FunctionToRename(int valueOne)

1 - 5 ■ R E N A M I N G A F U N C T I O N 17

Normally, you would use DllImport in your C# code to declare the function, like this:

[DllImport("FlatAPILib.DLL")]

public static extern int FunctionToRename(int anInt);

This means that PInvoke looks for the name FunctionToRename exported from theFlatAPILib.DLL Using this declaration, your managed code references this function with the

same name (FunctionToRename)

However, by adding the optional EntryPoint field to the DllImport attribute, you caneffectively rename the function:

[DllImport("FlatAPILib.DLL", EntryPoint="FunctionToRename")]

public static extern int RenamedFunction(int anInt);

The declaration looks like this in Visual Basic NET:

<DllImport("FlatAPILib.DLL", _

EntryPoint:="FunctionToRename")> _

Public Function RenamedFunction( _

ByVal anInt As Integer) As IntegerEnd Function

Once this is done, your managed code must reference the function with the newname of RenamedFunction When the function call is made, the actual entry point name of

FunctionToRenamewill be called

How It Works

You might need to rename a function like this for a number of reasons, including the following:

• The function name conflicts with another function Perhaps you are using multipleunmanaged libraries of functions, and the name has already been used in another library

• The name conflicts with your internal naming standards

• There are ANSI and wide (Unicode) versions of the same function and you need tospecify which one to use

• The function is written in such a way that it accepts untyped parameters In order toadd type safety to your managed code, you would like to declare the function multipletimes using different data types and possibly different names This would make theintent of the function clearer to anyone using it

■ Note An alternative to renaming a function is to create a managed wrapper for it Once this is done, any

potential problems with the function name are eliminated since the only class referencing the function is the

wrapper itself The managed wrapper then exposes methods that conform to the internal standards and do

not cause any naming conflicts See recipe 1-2 (Using the Function from Managed Code)

1 - 5 ■ R E N A M I N G A F U N C T I O N

18

A function might be written to accept any data type as an input parameter Internally, thefunction will determine the type of parameter that was passed in and process it accordingly

As an example, consider a function that is defined like this:

int PolymorphicFunction(void* anyValue, int dataType)

This function accepts one parameter that is type void*, meaning that any data type can

be passed to the function However, when we use this function from our managed code, wewould like to declare the function so that it is type-safe, accepting only valid types To accom-plish this, we can declare the same function multiple times in our code, each time using a differentname but pointing to the same entry point

■ Caution This is certainly not the recommended way to implement this unmanaged function This is simply

a manufactured example that demonstrates one possible use of renaming a function However, on occasion,you do need to interoperate with badly written unmanaged code such as this This example demonstrateshow you can use renaming, along with different method signatures, to apply some amount of type safety tothe function

Here is an example:

//first declaration of a function that accepts any type

[DllImport("FlatAPILib.DLL", EntryPoint="PolymorphicFunction")]

public static extern int FunctionWithInteger(

ref int anInt, int type);

//second declaration of a function that accepts any type

[DllImport("FlatAPILib.DLL", EntryPoint="PolymorphicFunction")]

public static extern int FunctionWithChar(

ref char aChar, int type);

In the example function, we might have discovered that it really accepts only two data types:

an integer or a Unicode character So as shown here, we declare the function twice, each timewith a different name and accepting a different data type In both declarations, the EntryPointdirects us to the same function within the unmanaged DLL

■ Note In this example, the first void*parameter is declared with the refmodifier This is necessary sincethe example function is expecting a pointer to an integer or char, rather than the value itself

With this in place, we can invoke the function with a small degree of type safety, knowingthat we’ve declared the function to accept only the allowed data types Exposing the function

in this way prevents someone from passing an unacceptable data type We can then call thefunction from C# using either one of our declared methods:

ByRef anInt As Integer, _ByVal type As Integer) As IntegerEnd Function

<DllImport("FlatAPILib.DLL", _

EntryPoint:="PolymorphicFunction")> _Public Function FunctionWithChar( _

ByRef aChar As Char, _ByVal type As Integer) As IntegerEnd Function

And code to execute these functions looks like this:

Dim myIntValue As Integer = 123

Dim result As Integer = FunctionWithInteger( _

myIntValue, 1)Console.WriteLine("Result from FunctionWithInteger = " _

+ result.ToString())Dim myCharValue As Char = "A"

result = FunctionWithChar( _

myCharValue, 2)Console.WriteLine("Result from FunctionWithChar = " _

public static extern int OverloadedFunction(

ref int anInt, int type);

//second overloaded version of a polymorphic function

[DllImport("FlatAPILib.DLL", EntryPoint="PolymorphicFunction")]

public static extern int OverloadedFunction(

ref char aChar, int type);