C# Complete by Sybex Inc Sybex © 2003 (974 pages) ISBN:0782142036 A clear picture of everything you need to know for developing applications using C# Companion Web Site BackCover C# Complete Introduction How This Book Is Organized A Few Typographic Conventions For More Information About the Contributors Chapter 1: Introduction to Visual C# and the NET Fram Developing Your First C# Program Introducing Visual Studio NET Using the NET Documentation Summary What's Next Chapter 2: Zen and Now¡ªThe C# Language Identifiers Keywords Variables Types Type Conversion Commenting Code Operators Flow Control Statements Structs Exceptions Summary What's Next Chapter 3: Strings, Dates, Times, and Time Spans Using Strings Creating Dynamic Strings Representing Dates and Times Using Time Spans Summary What's Next Chapter 4: Object-Oriented Programming Introducing Classes and Objects Declaring a Class Creating Objects Using Methods Defining Properties Working with Events Using Access Modifiers Creating and Destroying Objects Introducing Structs Summary What's Next Chapter 5: Derived Classes Introducing Inheritance Learning about Polymorphism Specifying Member Accessibility Hiding Members Versioning Using the System.Object Class Using Abstract Classes and Methods Declaring Sealed Classes and Methods Casting Objects Operator Overloading Summary What's Next Chapter 6: Arrays, Indexers, and Collections Arrays Indexers Collection Classes Summary What's Next Chapter 7: Reflecting on Classes Assemblies and Namespaces NET Namespaces Reflection Tracking Members with the Class View Window Navigating with the Object Browser Creating a Class Library What's Next Chapter 8: Building a Better Windows Interface Round Buttons Dancing ListBoxes Listing Menus Doing the Common Dialog Thing MDI Applications What's Next Chapter 9: Building Desktop Applications Desktop Application Types Writing Console Applications Resource Essentials Writing Windows Applications Application Debugging Summary What's Next Chapter 10: Working with Threads An Overview of Threads Working with Threads Understanding Critical Sections Understanding Thread Safety Using Your Knowledge What's Next Chapter 11: Overview of the ADO.NET Classes The Managed Provider and Generic Data Set Classes Performing a SQL SELECT Statement and Storing the R Summary What's Next Chapter 12: ADO.NET Application Development Comparing ADO to ADO.NET Using OleDbDataAdapter for Data Transfer to ADO.NET Writing a DataReader Application Writing a Dataset Application Importing and Exporting XML Example Using StringBuilder to Improve Performance Summary What's Next Chapter 13: Using DataSet Objects to Store Data The SqlDataAdapter Class The DataSet Class Writing and Reading XML Using a DataSet Object Mapping Tables and Columns Reading a Column Value Using Strongly Typed DataSet Creating a DataAdapter Object Using Visual Studio Creating a DataSet Object Using Visual Studio NET Summary What's Next Chapter 14: Using DataSet Objects to Modify Data The DataRow Class The DataColumn Class Adding Restrictions to DataTable and DataColumn Obj Finding, Filtering, and Sorting Rows in a DataTable Modifying Rows in a DataTable Retrieving New Identity Column Values Using Stored Procedures to Add, Modify, and Remove Automatically Generating SQL Statements Exploring the DataAdapter and DataTable Events Dealing with Update Failures Using Transactions with a DataSet Modifying Data Using a Strongly Typed DataSet Summary What's Next Chapter 15: Introduction to C# Web Applications The web.config and machine.config Files Site Hierarchy versus Directory Hierarchy Inside Configuration Files Creating Custom Configuration Sections Configuration File Location and Lock Settings What's Next Chapter 16: Using XML in Web Applications Introduction to the System.Xml Namespace Reading XML Documents Using the XmlDataDocument Class The XmlException Classes Performing XSLT Transforms Programmatically What's Next Chapter 17: Web Services Building a Web Service Consuming a Web Service SOAP (Simple Object Access Protocol) Finding Web Services (UDDI) What's Next Chapter 18: Building Your Own Web Controls Building a User Control Building a Composite Control Building a Custom Server Control Transferring Data Between ASP.NET Web Forms and Com What's Next Chapter 19: Overcoming Holes inthe NET Framework Why Access the Win32 API? Win32 Access for C# Developers Win32 Access for Visual Basic Developers Summary What's Next Chapter 20: Overcoming Security Issues An Overview of Windows Security Using the Access Control Editor Using the Security Configuration Editor Understanding How NET Role-Based Security Differs Looking Up an Account SID Example Using the GetFileSecurity() Function Example Working with an ACEs Example Summary What's Next Chapter 21: Getting Started with the Mobile Internet T Introducing the Microsoft Mobile Internet Toolkit The Openwave SDK Supported Devices Getting Started Building a Simple Two-Card Deck Using Code Behind Summary Bonus Chapter: Working with Win32 API Data A Short View of Data Working with Variables Working with Data Structures Working with Pointers Working with Enumerations Importing Resources Summary Back Cover C# Complete is a one-of-a-kind book valuable both for its broad content and its low price Whether you're brand-new to C# programming, are migrating from Visual Basic or Visual C++ to C#, or have already developed some expertise in C#, you'll get the skills you need to become proficient with Microsoft's powerful new language designed for the NET platform Creating complex applications in the NET Framework is made easier with C# Microsoft's first true object-oriented programming language In C# Complete, you'll get a clear picture of everything you need to know for developing applications using C# You'll begin by learning the essential elements of the language and of Visual Studio NET, in which you'll develop and run programs in a comprehensive integrated development environment You'll see how to create functional and exciting user interfaces and desktop applications written with C#, and how to incorporate threads to their best advantage You'll explore the use of ADO.NET classes in development of C# database applications Chapters on ASP.NET Web Services will walk you through the building of an XML web services application You'll also visit some advanced topics, including designing with security in mind, overcoming the shortcomings of the NET Framework, and working with the Microsoft Mobile Internet Toolkit C# Complete introduces you to the work of some of Sybex's finest authors, so you'll know where to go to learn even more about C# and the NET Framework C# Complete Associate Publisher: Joel Fugazzotto Acquisitions Editor: Denise Santoro Lincoln Developmental Editor: Carol Henry Compilation Editor: Matt Tagliaferri Production Editor: Kelly Winquist Copyeditor: Rebecca Rider Compositor: Rozi Harris, Interactive Composition Corporation Proofreaders: Nancy Riddiough, Yariv Rabinovitch, Emily Hsuan, Leslie Higbee Light, Laurie O'Connell, Monique Vandenberg Indexer: Nancy Guenther Book Designer: Maureen Forys, Happenstance Type-O-Rama Cover Designer: Design Site Cover Illustrator: Suza Scalora, PhotoDisc Copyright © 2003 SYBEX Inc., 1151 Marina Village Parkway, Alameda, CA 94501 World rights reserved No part of this publication may be stored in a retrieval system, transmitted, or reproduced in any way, including but not limited to photocopy, photograph, magnetic, or other record, without the prior agreement and written permission of the publisher Library of Congress Card Number: 2002115481 ISBN: 0-7821-4203-6 SYBEX and the SYBEX logo are either registered trademarks or trademarks of SYBEX Inc in the United States and/or other countries Screen reproductions produced with FullShot 99 FullShot 99 © 1991– 1999 Inbit Incorporated All rights reserved.FullShot is a trademark of Inbit Incorporated Screen reproductions produced with Collage Complete Collage Complete is a trademark of Inner Media Inc Netscape Communications, the Netscape Communications logo, Netscape, and Netscape Navigator are trademarks of Netscape Communications Corporation Netscape Communications Corporation has not authorized, sponsored, endorsed, or approved this publication and is not responsible for its content Netscape and the Netscape Communications Corporate Logos are trademarks and trade names of Netscape Communications Corporation All other product names and/or logos are trademarks of their respective owners Internet screen shot(s) using Microsoft Internet Explorer reprinted by permission from Microsoft Corporation TRADEMARKS: SYBEX has attempted throughout this book to distinguish proprietary trademarks from descriptive terms by following the capitalization style used by the manufacturer The author and publisher have made their best efforts to prepare this book, and the content is based upon final release software whenever possible Portions of the manuscript may be based upon pre-release versions supplied by software manufacturer(s) The author and the publisher make no representation or warranties of any kind with regard to the completeness or accuracy of the contents herein and accept no liability of any kind including but not limited to performance, merchantability, fitness for any particular purpose, or any losses or damages of any kind caused or alleged to be caused directly or indirectly from this book Manufactured in the United States of America 10 9 8 7 6 5 4 3 2 1 important when working with data structures that contain a lot of C data types that don't convert well to managed data types Make sure you create a managed data structure—it's possible to create both managed and unmanaged code in Visual C++, which gives it an advantage when working with this type of code Ultimately the content of the structure must break down into types that C# and Visual Basic will understand as shown in the following code [StructLayout(LayoutKind::Sequential)] public gc struct DVTARGETDEVICE { public: UInt32 tdSize; short tdDriverNameOffset; short tdDeviceNameOffset; short tdPortNameOffset; short tdExtDevmodeOffset; char tdData; }; Notice that the structure relies on native Visual C++ types, in many cases, because these types translate well into standard NET Framework types However, there are some situations when a native Visual C++ type could cause problems, as in the case of an unsigned integer (UINT) In this case, make sure you use the NET Framework equivalent type directly (UInt32) There are other problems to consider when working with structures For example, a structure must include the [StructLayout] attribute so that CLR knows how to work with the data it contains Generally, you'll use the LayoutKind::Sequential argument for Windows function calls This value ensures that CLR doesn't rearrange or optimize the structure in any way Note that Visual C++ requires the use of the gc keyword for managed structures and that you must make all of the data elements public so that they appear within the managed environment Structures become problematic in some situations For example, you'll find that some structures contain other structures The level of nesting can become absurd in some situations In those cases, you need to determine if the level of nesting is warranted If not, you can usually provide a substitute value For example, if the code you create will never pass the structure to Windows (in other words, the structure is always passed as a NULL value), you can normally use an int as a substitute for the structure Make sure you document any deviations within the DLL source code and as part of the DLL documentation Note Don't worry if you don't quite grasp all of the nuances of this next example The sole purpose of this example is to show you that it's possible to create the structures that Win32 API calls require outside of the base programming environment This is an especially important technique when the data structure contains unions or other complexities that you can't duplicate in the managed environment Finally, there are some extreme cases when you can use the ability of Visual C++ to work with both managed and unmanaged code to your advantage Create a function within Visual C++ that accepts all of the data required to create the data structure in question, then create that data structure within the Visual C++ code Make sure you change the Win32 API function call definition to match the new setup Listing 1.2 is an example of such a construction technique Listing 1.2: A Technique for Creating Data Structures Externally // Creates a typical data structure void CreateDVTargetDevice(IntPtr* StructOut, Int16 tdDriverNameOffset, Int16 tdDeviceNameOffset, Int16 tdPortNameOffset, Int16 tdExtDevmodeOffset, Char tdData, Int32 tdSize) { DVTARGETDEVICE *Output; // Ouput value void* lpData = malloc(sizeof(DVTARGETDEVICE)); // Allocate memory for the return data Output = (DVTARGETDEVICE*)lpData; // Fill the data structure Note the use of boxing and // data conversion for tdData box Char* tdDataBoxed = box(tdData); Output->tdData[0] = tdDataBoxed->ToByte(NULL); Output->tdDeviceNameOffset = tdDeviceNameOffset; Output->tdDriverNameOffset = tdDriverNameOffset; Output->tdExtDevmodeOffset = tdExtDevmodeOffset; Output->tdPortNameOffset = tdPortNameOffset; Output->tdSize = tdSize; // Return the structure as a pointer *StructOut = IntPtr(lpData); } As you can see, the output of this function is an IntPtr, which makes it easy to use with any of the NET programming languages The code has to allocate a local pointer in order to provide a place for data output However, placing data within a void* doesn't work particularly well, so you need to assign that memory to a local copy of the data structure in question Notice that you might have to perform some data conversion For example, this data structure requires that you box the tdData value, convert it to a Char, and finally place it within the data structure The wrapper DLL also includes a conversion function that accepts the IntPtr as input, converts it to a string, and enables the calling application to display the data on screen You'd never do this in a real application, but it's important to see how the IntPtr concept works and this is the easiest way to demonstrate it Listing 1.3 shows the important test code Listing 1.3: A Test Program for the External Structure private void btnTest_Click(object sender, System.EventArgs e) { CreateStructs NewStruct; // Create Structure Object // IntPtr Containing Structure IntPtr ResultPtr; // String Containing Original Data String ResultStr; // Initialize the data objects NewStruct = new CreateStructs(); ResultPtr = new IntPtr(0); // Create the new structure NewStruct.CreateDVTargetDevice( ref ResultPtr, 1, 2, 3, 4, 'a', 16); // Create a string from the new structure ResultStr = NewStruct.ReturnDVTargetDevice(ResultPtr); // Make sure you free the unmanaged memory NewStruct.FreePointer(ResultPtr); // Display the application output MessageBox.Show(ResultStr, "Structure Output", MessageBoxButtons.OK, MessageBoxIcon.Information); } Notice that the CreateDVTargetDevice() function accepts the structure values as single inputs—negating the requirement to work with the data structure within the managed environment The function returns an IntPtr that you can pass to Win32 API functions as needed As noted in the source code comments, make sure you free the unmanaged memory pointer before the application exits, or the application will have a memory leak Figure 1.5 shows the output from this example Figure 1.5: This example shows that it's possible to create data structures outside the managed environment You might wonder how well Visual Basic works with this particular application since it still requires a pointer A look at the Object Browser (shown in Figure 1.6) shows that this wrapper DLL doesn't present any problems Visual Basic correctly interprets the pointer as a ByRef reference In short, this technique is the perfect way to get around many of the problems of working with Visual Basic and the Win32 API Figure 1.6: The technique shown in this section overcomes many of the problems Visual Basic has with pointers Working with Pointers As you've already seen in other areas of this chapter, pointers can present problems for both Visual Basic and C# developers However, this is one area where C# developers have a decided advantage and you might find that it's better to use C# whenever you have a lot of pointers to work with Even if Visual Basic is the main language for your application, you can write a wrapper DLL in C# to meet the requirements of the Win32 API call portion of the code Generally, anywhere you need to use a UInt value or an odd pointer, you'll also need to use C# The IntPtr is the developer's best friend when it comes to pointers However, remember that an IntPtr contains a void*, not the specialized pointers that Win32 API calls rely on As shown in Listing 1.2, the use of a void* normally means some type of data conversion later in the process The whole concept of a void* is to represent a pointer of an unknown type In sum, an IntPtr enables you to create generic pointers, but not specific pointers C# developers also have access to standard C-like pointers However, to use this feature you must declare the affected method as unsafe As discussed in the "Understanding the Effects of Unsafe Code" section of Chapter 20 of C# Complete, you want to minimize unsafe code sections for a number of reasons The most important reason is that unsafe code sections don't receive the same level of error checking that normal code sections do, which means that your code is more likely to contain hidden (and difficult to debug) errors Here are some general rules for using normal pointers Use an IntPtr whenever possible Keep sections with standard pointers small Perform more error checking than normal Include range checks of all data to ensure that it remains within limits Isolate unsafe code sections from the main application whenever possible Consider using Visual C++ for large numbers of pointers Avoid using pointers by substituting managed alternatives Working with Enumerations Windows relies extensively on enumerated data types These data types normally begin with the enum keyword However, as you'll notice in Listing 1.1, duplicating a Windows enumerated type with a managed enumeration is difficult You can always use an enumeration for return values from a Windows API call, but you can't always use it as input The exception is when the enumerated type will appear singly and not as part of an or-ed or and-ed input The MessageBoxEx() function provides a perfect example of the enumerated type problem because you can't use an enumeration to create the input required by the function In these cases, you need to create a class consisting entirely of constants Note that there are differences between Visual Basic and C# when working with the class form of an enumeration When you work with C#, you can declare the type of the constant For example, in the MessageBoxEx() example, all of the constants are of the UInt32 type because that's what the function requires Visual Basic doesn't allow this distinction and it can cause problems For example, here's the Visual Basic version of the MBButton class ' Create a list of buttons Public Class MBButton Public Const MB_OK = &H0 Public Const MB_OKCANCEL = &H1 Public Const MB_ABORTRETRYIGNORE = &H2 Public Const MB_YESNOCANCEL = &H3 Public Const MB_YESNO = &H4 Public Const MB_RETRYCANCEL = &H5 Public Const MB_CANCELTRYCONTINUE = &H6 Public Const MB_HELP = &H4000 End Class Tip Notice the use of hexadecimal numbers in the MBButton class It's usually easier to present the numbers in this form than it is to use decimal equivalents The Win32 API documentation normally relies on hexadecimal number input, rather than decimal numbers, so using hexadecimal numbers makes your code easier to debug In some cases, working with enumerations and classes becomes so difficult that you might want to define the enumeration as a series of defines or constant values In fact, the C header files often use this technique when creating an enumeration would prove too complex Looking into the C header file will often provide you with clues as to the correct enumeration representation in your own code Enumerations become even more difficult when working with wrapper DLLs The most important reason is that the enum will never appear in the Object Browser and the wrapper DLL user won't be able to access it Consequently, you need an alternative for creating enumerated types In most cases, using a class is the best answer because you have good control over how the class will appear to the end user However, many situations will call for use of defines or constants in wrapper DLLs Importing Resources Resource usage is an important part of any development project You manage memory, disk space, and other physical resource elements as part of the development project In addition, most developers are used to finding icons and other graphic resources embedded within DLLs found in the Windows directory Finally, resources can be code —the embodiment of executable code within an external DLL is a type of resource that most developers are used to having This section discusses three main issues First, it tells you how the NET Framework can help you manage resources located in external files, such as the graphic images located in the Shell32.DLL file Second, we discuss the issue of using external DLLs from your managed code Finally, we'll take a quick look at some of the issues involved in using resources with the Win32 API Understanding NET Framework Functionality It's important to remember that the NET Framework does provide the functionality required to display basic graphics For example, you can embed a bitmap within your application and display it on screen as needed Here's the basic code needed to perform the task private void btnTest_Click(object sender, System.EventArgs e) { // Retrieve an embedded bitmap from the current assembly Assembly Asm = Assembly.GetExecutingAssembly(); Stream Strm = Asm.GetManifestResourceStream("NETBitmap.Main.bmp"); Bitmap Temp = new Bitmap(Strm); // Display the bitmap on screen pbMain.Image = (Image)Temp; } As you can see, this example relies on reflection to get the job done You must set the Build Action property of the bitmap or other resource to Embedded Resource to use this technique Figure 1.7 shows the output from this example Figure 1.7: Displaying an embedded bitmap within your NET application is fine for the managed environment The resulting bitmap works fine within the managed environment but won't work within the Win32 API, which means you have to use a different technique when making a Win32 API call The Win32 API doesn't understand the managed resources created by reflection Fortunately, you can use the special GetHbitmap() call to answer many Win32 API call needs The hBitmap this call returns is Windows compatible You must make a call to the Win32 API DeleteObject() function to deallocate the handle when you finish using it Here's the declaration for the DeleteObject() function [DllImport("gdi32.dll")] public static extern int DeleteObject(IntPtr hObject); Using the IDE Features You'll find that you need to use wrapper DLLs regularly when creating connections between the NET Framework and the Win32 API Using wrapper DLLs enhances code reuse and enables you to use other languages as needed Of course, this means adding a reference to the external DLL so that you can access the code it contains from within your application The following steps tell how to add such a reference (the same procedure works whether you use Visual Basic or C#) Right-click the References folder in Solution Explorer and choose Add Reference from the context menu You'll see an Add Reference dialog box similar to the one shown in Figure 1.8 Notice that there are separate tabs for NET, COM, and Project related references Generally, you won't find custom DLLs on any of these tabs, but it always pays to look Figure 1.8: The Add Reference dialog box enables you to add custom references to your application Locate and select the reference you want to add to your application Add the reference to the Selected Components list by highlighting it and clicking Select If you don't see the DLL, you'll need to add it manually as described in step 3 Otherwise, you can skip step 3 and proceed to step 4 Click Browse and you'll see a Select Component dialog box Use this dialog box as you would any file open dialog box to locate the file containing the executable code Once you locate the file, highlight it and click Open Click OK You should see the new reference added to the Reference folder Add a statement to use the new reference to your application For C# developers, this means adding a using statement to the beginning of the file For Visual Basic developers this means adding an Imports statement to the beginning of the file Working with the Win32 API Working directly with the Win32 API means locating the various functions you need—they're not all in the same DLL In many cases, you'll need to perform esoteric tasks such as gaining access to the current application instance using the Marshal.GetHINSTANCE() method You'll also need to know how to gain access to the current application handle using this.Handle However, in many cases, it's a matter of performing straight coding as shown here [DllImport("user32.dll")] public static extern IntPtr LoadBitmap(IntPtr hInstance, [MarshalAs(UnmanagedType.LPStr)]String lpBitmapName); [DllImport("gdi32.dll")] public static extern int DeleteObject(IntPtr hObject); private void btnTest_Click(object sender, System.EventArgs e) { IntPtr HBitmap; // A handle to a bitmap // Load the bitmap using a Windows call HBitmap = LoadBitmap(IntPtr.Zero, "D:\\Main.bmp"); // Display the bitmap on screen pbMain.Image = Image.FromHbitmap(HBitmap); // Delete the hBitmap DeleteObject(HBitmap); } This code represents an alternative way to load a bitmap from disk Essentially all you need to do is load the bitmap, convert it to an image, and then release memory used by the bitmap The tricky part is setting everything up so that Windows understands what you want to do Once you have the required function calls in place, using the Win32 API calls is about as difficult as using their NET Framework equivalents Summary This chapter has demonstrated one of the basic principles of using the Win32 API from the managed environment—data translation The managed and unmanaged environments only work together when the data they share is formatted correctly In some situations, you can perform a direct data transfer, but in other cases you have to marshal the data or get creative and construct the data using other techniques At this point, you have seen enough examples to begin writing some code yourself You should try creating a few examples that translate data that you need to work with to and from the unmanaged environment It's important to start small, as we did with the MessageBoxEx() example You'll find that the debugger is lacking when it comes to this type of application programming, so you have to know how a data translation will affect your application and the Win32 API calls that it makes ... Next, to move to the C# programs directory, you enter cd followed by C# programs: cd C# programs To compile Example1_1.cs using csc, you enter the following command: csc Example1_1.cs Notice that the name of the program source file follows csc—it's... 1999 Inbit Incorporated All rights reserved.FullShot is a trademark of Inbit Incorporated Screen reproductions produced with Collage Complete Collage Complete is a trademark of Inner Media Inc Netscape Communications, the Netscape Communications logo,... Collage Complete is a trademark of Inner Media Inc Netscape Communications, the Netscape Communications logo, Netscape, and Netscape Navigator are trademarks of Netscape Communications Corporation Netscape Communications Corporation has not authorized,