ado.net in a nutshell

[ Team LiB ] • Table of C ontents • Index • Reviews • Examples • Reader Reviews • Errata A DO.NET in a Nutshell By Bill Hamilton, Matthew MacDonald Publishe r: O 'Re illy Date Publishe d : April 2003 ISBN: 0-596-00361-7 Pa ge s: 620 ADO.NET in a Nutshell is the most complete and c oncise source of ADO .NET information available. Besides being a valuable reference, this book covers a variety of issues that programmers face when developing web applications or web services that rely on database acc ess. Most examples use Mic rosoft's C# language. T he book's CD includes an add-in to integrate the reference with Visual Studio .NET help files. [ Team LiB ] 1 / 611 [ Team LiB ] • Table of C ontents • Index • Reviews • Examples • Reader Reviews • Errata A DO.NET in a Nutshell By Bill Hamilton, Matthew MacDonald Publishe r: O 'Re illy Date Publishe d : April 2003 ISBN: 0-596-00361-7 Pa ge s: 620 Copyright Prefa ce Audie nce Conte nts of T his Bo ok W ha t's on the C D-R O M Conve ntio ns U se d in T his Bo o k Com m e nts a nd Q uestions Ack no wle dgm ents Pa rt I: ADO .NET Tutoria l Chapte r 1. Introd uction Se ction 1.1. ADO .NET Da ta P rovide rs Se ction 1.2. C onne cte d and Dis co nnecte d Data Chapte r 2. .NET Da ta P ro vid e rs Se ction 2.1. Da ta P rovide rs Se ction 2.2. Se le cting a Da ta Provider Se ction 2.3. C rea ting a Custom Da ta Provider Chapte r 3. Co nnections Se ction 3.1. C onne ction O bject O vervie w Se ction 3.2. T he Co nnection String Se ction 3.3. O pe ning a nd Closing C onne ctions Se ction 3.4. C onne ction P o o ling Chapte r 4. Co m m ands Se ction 4.1. C om ma nd O bject O vervie w Se ction 4.2. C rea ting a nd Ex e cuting a C o mm and Se ction 4.3. P aram ete r O bject O ve rvie w Se ction 4.4. P aram ete rize d C o mm ands Se ction 4.5. C om ma nds with Sto re d P rocedures Se ction 4.6. C om ma nds a nd Da ta De finitio n La ng ua g e (DDL) Chapte r 5. Data Re ade rs Se ction 5.1. Da taR ea der O bject O verview Se ction 5.2. P erform ing a Q ue ry with a Data Re ade r Se ction 5.3. Sto re d Procedure s with the Da taR ea d e r Se ction 5.4. Da taR ea ders and Sche m a Inform ation Chapte r 6. Data Sets Se ction 6.1. C rea ting a n Untype d Da taSet 2 / 611 Se ction 6.2. Work ing with Table s in the Da taSet Se ction 6.3. Adding a nd R em oving R ela tio ns Se ction 6.4. Adding C usto m Inform a tion Se ction 6.5. C loning the Sche ma Se ction 6.6. C opying the Da taSe t Se ction 6.7. Me rging Two Da taSe ts Se ction 6.8. R em oving All Data Se ction 6.9. R ese tting the Da taSe t Se ction 6.10. C o mm itting a nd Disca rding C ha ng e s Chapte r 7. Data Ta ble s Se ction 7.1. C rea ting a Data Table Se ction 7.2. Work ing with Colum ns Se ction 7.3. C onstraints Se ction 7.4. P rim ary Ke y Se ction 7.5. R ows Se ction 7.6. Lo ading Da ta Se ction 7.7. C om mitting and Disca rd ing Changes Se ction 7.8. C loning the Sche ma of the Table Se ction 7.9. C opying the Ta ble Se ction 7.10. Selecting a Sub se t o f Ro ws Se ction 7.11. Pe rform ing Aggrega te C a lcula tions Se ction 7.12. R e moving All Da ta Se ction 7.13. R e setting the Table Se ction 7.14. Identifying Errors in the Table Se ction 7.15. Data Table Eve nts Chapte r 8. Data Co lum ns Se ction 8.1. C rea ting Da taC olum ns Se ction 8.2. C rea ting AutoIncrem ent C olum ns Se ction 8.3. C rea ting Ex pression Co lum ns Se ction 8.4. Handling Null Va lues Se ction 8.5. Mapping .NET Da ta Provider Type s to .NET Fram ework Types Chapte r 9. Data Ro ws Se ction 9.1. C rea ting a Data Ro w Se ction 9.2. Updating R o ws Se ction 9.3. De leting Rows Se ction 9.4. Using R ow Sta te Info rm ation Se ction 9.5. Using R ow Versio n Info rm ation Se ction 9.6. Accepting or R ejecting Changes to R o ws Se ction 9.7. Naviga ting P a re nt a nd C hild R o ws Se ction 9.8. Using R ow Error Inform atio n Chapte r 10. C onstraints Se ction 10.1. C o nstra int O bject O vervie w Se ction 10.2. The Unique C onstraint Se ction 10.3. The Fore ignKe yC o nstra int Chapte r 11. Da taR ela tio ns Se ction 11.1. Data Re lation O bject O vervie w Se ction 11.2. Navigating Re la tiona l Data Chapte r 12. Da taViews a nd Da ta Binding Se ction 12.1. The Da taView a nd Da taViewManage r Se ction 12.2. Sorting a nd Filtering Se ction 12.3. Access ing Data Through a Da taView Se ction 12.4. W indows Da ta Bind ing Se ction 12.5. ASP.NET Da ta Binding Chapte r 13. Strongly Type d Data Sets Se ction 13.1. C re a ting a Strongly Type d Da taSe t Se ction 13.2. Add ing a R ow Se ction 13.3. Editing a R ow Se ction 13.4. Finding a R o w Se ction 13.5. Null Da ta Se ction 13.6. Navigating Hierarchical Data Se ction 13.7. Annota tions Chapte r 14. Da taAdapte rs Se ction 14.1. C re a ting Da taAda p ter O b ject 3 / 611 Se ction 14.2. R e trieving Data from the Data Source Se ction 14.3. R e trieving Sche m a Inform ation from the Da ta Source Se ction 14.4. Upda ting the Da ta Source Se ction 14.5. Ma pping Ta ble s a nd C olum ns Se ction 14.6. AcceptChange sDuringFill Se ction 14.7. C o ntinueUpdate OnError Se ction 14.8. Data Ada pte r Eve nts Chapte r 15. Updating the Da ta So urce Se ction 15.1. SqlC om ma ndBuilde r C la s s O vervie w Se ction 15.2. Upda ting a Da ta Source Using C o m m and Build e r Se ction 15.3. Upda ting a Da ta Source Using C usto m Logic Se ction 15.4. R e freshing Da ta Afte r Upda ting Se ction 15.5. R e trieving Up d a ted Values from the Da ta Source Se ction 15.6. Upda ting Da ta in R elate d Ta ble s Se ction 15.7. Ha ndling C oncurrency Issue s Se ction 15.8. O ptim iza tio n Chapte r 16. Tra nsactions Se ction 16.1. Ma nua l Tra nsa ctio ns Se ction 16.2. Isola tion Le ve ls Se ction 16.3. Save points Se ction 16.4. Neste d Tra nsactions Se ction 16.5. Trans a ctions Using a Da taAdapte r Se ction 16.6. Autom atic Transactions Chapte r 17. XML and the Da taSe t Se ction 17.1. Data Set XML Methods Se ction 17.2. Sha ping DataSe t XML Se ction 17.3. O ther .NET XML C lasses Se ction 17.4. Xm lDa taDo cum ent O b ject O verview Se ction 17.5. Using the Da ta O b jects to Edit XML Se ction 17.6. SQ L Se rve r 2000 XML Pa rt II: ADO .NET C o re C lasse s Chapte r 18. T he Co nnection C la s s Se ction 18.1. C o mm ents/Trouble sho oting Se ction 18.2. Prope rtie s R eference Se ction 18.3. Me thods R efe rence Se ction 18.4. Eve nts R eference Chapte r 19. T he Co m m and Class Se ction 19.1. C o mm ents/Trouble sho oting Se ction 19.2. Prope rtie s R eference Se ction 19.3. C o lle ctio ns R e fe rence Se ction 19.4. Me thods R efe rence Chapte r 20. T he Pa ra m ete r Class Se ction 20.1. C o mm ents/Trouble sho oting Se ction 20.2. Prope rtie s R eference Chapte r 21. T he Data Re ade r C lass Se ction 21.1. C o mm ents/Trouble sho oting Se ction 21.2. Prope rtie s R eference Se ction 21.3. Me thods R efe rence Chapte r 22. T he Data Set C lass Se ction 22.1. C o mm ents/Trouble sho oting Se ction 22.2. Prope rtie s R eference Se ction 22.3. C o lle ctio ns R e fe rence Se ction 22.4. Me thods R efe rence Se ction 22.5. Eve nts R eference Chapte r 23. T he Data Table C lass Se ction 23.1. C o mm ents/Trouble sho oting Se ction 23.2. Prope rtie s R eference Se ction 23.3. C o lle ctio ns R e fe rence Se ction 23.4. Me thods R efe rence Se ction 23.5. Eve nts R eference 4 / 611 Chapte r 24. T he Data Co lum n Class Se ction 24.1. C o mm ents/Trouble sho oting Se ction 24.2. Prope rtie s R eference Se ction 24.3. C o lle ctio ns R e fe rence Chapte r 25. T he Data Ro w Class Se ction 25.1. C o mm ents/Trouble sho oting Se ction 25.2. Prope rtie s R eference Se ction 25.3. C o lle ctio ns R e fe rence Se ction 25.4. Me thods R efe rence Chapte r 26. T he Co nstraint C la s s Se ction 26.1. C o mm ents/Trouble sho oting Se ction 26.2. Prope rtie s R eference Se ction 26.3. C o lle ctio ns R e fe rence Chapte r 27. T he Data Re lation Class Se ction 27.1. C o mm ents/Trouble sho oting Se ction 27.2. Prope rtie s R eference Se ction 27.3. C o lle ctio ns R e fe rence Chapte r 28. T he Data Vie w Class Se ction 28.1. C o mm ents/Trouble sho oting Se ction 28.2. Prope rtie s R eference Se ction 28.3. Me thods R efe rence Se ction 28.4. Eve nts R eference Chapte r 29. T he Data Ada pter C la s s Se ction 29.1. C o mm ents/Trouble sho oting Se ction 29.2. Prope rtie s R eference Se ction 29.3. C o lle ctio ns R e fe rence Se ction 29.4. Me thods R efe rence Se ction 29.5. Eve nts R eference Chapte r 30. T he Co m m andBuilde r C lass Se ction 30.1. C o mm ents/Trouble sho oting Se ction 30.2. Prope rtie s R eference Se ction 30.3. Me thods R efe rence Chapte r 31. T he Transa ction Class Se ction 31.1. C o mm ents/Trouble sho oting Se ction 31.2. Prope rtie s R eference Se ction 31.3. Me thods R efe rence Pa rt III: AP I Q uick R e fe re nce Chapte r 32. How to Use This Q uick R efe rence Se ction 32.1. Finding a Q uick-R eference Entry Se ction 32.2. R e ading a Q uick-Re ference Entry Chapte r 33. C onve rting from C # to VB Synta x Se ction 33.1. Gene ra l C onside ra tio ns Se ction 33.2. C la sse s Se ction 33.3. Structures Se ction 33.4. Interfa ce s Se ction 33.5. C la ss, Structure , a nd Inte rfa ce Me mbe rs Se ction 33.6. De le g a tes Se ction 33.7. Enum era tio ns Chapte r 34. T he Syste m .Da ta Nam espace Acce ptR ejectR ule Com m a ndBe ha vior Com m a ndType ConnectionState Constraint ConstraintCo llection ConstraintException Data Co lum n Data Co lum nC hangeEve ntArgs Data Co lum nC hangeEve ntHandle r Data Co lum nC olle ction 5 / 611 Data Ex ceptio n Data Re lation Data Re lationC olle ction Data Ro w Data Ro wAction Data Ro wC hange Eve ntArgs Data Ro wC hange Eve ntHa ndler Data Ro wC olle ction Data Ro wSta te Data Ro wVersion Data Ro wView Data Set Data SysDe scriptionAttribute Data Table Data TableC olle ction Data Vie w Data Vie wMa na ge r Data Vie wR owSta te Data Vie wSe tting Data Vie wSe tting C olle ction DBC oncurrencyException DbType Delete dR o wIna ccessible Ex ce ption Duplica teNam eException Evalua teEx ception FillErrorEve ntArgs FillErrorEve ntHa ndle r Fo re ignKeyConstraint IC olum nMa pping IC olum nMa pping C olle ction IDa taAda pte r IDa taP aram ete r IDa taP aram ete rC olle ction IDa taR ea der IDa taR eco rd IDb C om ma nd IDb C onne ction IDb Da taAdapte r IDb Da taP aram ete r IDb Transaction InR owC ha nging Eve ntException Inte rnalDa taColle ctionBa se InvalidC onstraintEx ce ption InvalidEx pressionException Is o lationLeve l ITa ble Ma pping ITa ble Ma ppingCo llection Ma pp ingType Me rg e Faile dEve ntArgs Me rg e Faile dEve ntHandle r MissingMa ppingActio n MissingPrim aryKe yExce ption MissingSche m aActio n NoNullAllo wedExce p tio n Pa ram ete rDirection PropertyAttributes PropertyC olle ction Re adO nlyEx ce ption Ro wNotInTable Ex ce ption Rule Schem aType SqlDbType State ChangeEve ntArgs State ChangeEve ntHa ndler State mentType StrongTypingEx ception Syntax ErrorException Type dDa taSetGe nerato r Type dDa taSetGe nerato rExce p tio n Unique Co nstra int 6 / 611 Up da teR owSource Up da teSta tus Ve rsio nNotFound Ex ce ptio n Xm lR e adMode Xm lW riteMode Chapte r 35. T he Syste m .Da ta.C om m o n Nam esp a ce Data Ada p ter Data Co lum nMa pping Data Co lum nMa pping C olle ction Data TableMapping Data TableMappingC o lle ctio n DbDa taAda pte r DBDa taP e rm issio n DBDa taP e rm issio nAttrib ute DbDa taR eco rd DbEnum erato r Ro wUpdate dEve ntArgs Ro wUpdatingEventArgs Chapte r 36. T he Syste m .Da ta.SqlClie nt Nam espa ce SqlClientP e rm iss ion SqlClientP e rm iss ionAttribute SqlCo m m and SqlCo m m andBuilde r SqlCo nne ction SqlData Ada pte r SqlData Re ade r SqlError SqlErrorCo llection SqlException SqlInfo Me ssage Eve ntArgs SqlInfo Me ssage Eve ntHa ndler SqlPa ra m ete r SqlPa ra m ete rCo llection SqlR o wUpda tedEve ntArgs SqlR o wUpda tedEve ntHa ndle r SqlR o wUpda tingEve ntArgs SqlR o wUpda tingEve ntHandle r SqlTrans a ction Chapte r 37. T he Syste m .Da ta.O leDb Nam esp a ce O le Db C om ma nd O le Db C om ma ndBuilder O le Db C onne ction O le Db Da taAdapte r O le Db Da taR ea der O le Db Error O le Db ErrorC o lle ctio n O le Db Ex ce ptio n O le Db InfoMessa ge Eve ntArgs O le Db InfoMessa ge Eve ntHandle r O le Db P aram ete r O le Db P aram ete rC o lle ctio n O le Db P erm iss ion O le Db P erm iss ionAttribute O le Db R owUpdate dEventArgs O le Db R owUpdate dEventHa nd le r O le Db R owUpdatingEve ntArgs O le Db R owUpdatingEve ntHa nd le r O le Db Sche ma Guid O le Db Transaction O le Db Type Chapte r 38. T he Syste m .Da ta.SqlTypes Nam esp a ce INullable SqlBinary SqlBo ole an SqlByte SqlCo m pa reO ptions SqlDateTim e 7 / 611 SqlDecim al SqlDouble SqlGuid SqlInt16 SqlInt32 SqlInt64 SqlMo ne y SqlNullVa lueExce p tio n SqlSingle SqlString SqlTruncate Ex ceptio n SqlType Ex ception Pa rt IV: Appendix es Appe ndix A. ADO .NET P rovide rs Se ction A.1. T he SQ L Se rve r P rovide r Se ction A.2. T he O LE DB P rovide r Se ction A.3. T he O DBC .NET Provider Se ction A.4. T he O ra cle .NET P rovide r Se ction A.5. T he O DP.NET P rovide r Appe ndix B. ADO .NET XML Ex tensions Se ction B.1. co de ge n Nam espa ce Se ction B.2. m sda ta Nam espa ce Se ction B.3. diffgr Nam espace Appe ndix C . Microsoft Data Engine (MSDE) Se ction C .1. Installing MSDE Se ction C .2. MSDE Ess e ntials Se ction C .3. Adding the Northwind Da ta Se ction C .4. Migrating MSDE to SQ L Se rve r Type , Me tho d, Property, and Fie ld Index A-L M-Z Colophon Inde x [ Team LiB ] 8 / 611 [ Team LiB ] Copyright Copyright © 2003 O'Reilly & A s sociates, Inc. Printed in the United States of America. Published by O 'Reilly & As sociates, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472. O 'Reilly & A ssociates books may be purchased for educational, business, or sales promotional use. O nline editions are also available for most titles (http://safari.oreilly.com). For more information, contact our corporate/institutional sales department: (800) 998-9938 or corporate@oreilly.com. Nutshell Handbook, the Nutshell Handbook logo, and the O'Reilly logo are registered trademarks of O'Reilly & Associates, Inc. Many of the des ignations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O'Reilly & A ssociates, Inc. was aware of a trademark claim, the des ignations have been printed in caps or initial caps. Microsoft, the .NET logo, Visual Basic .NET, V isual Studio .NET, A DO .NET, Windows, and Windows 2000 are regis tered trademarks of Microsoft C orporation. The association between the image of an Afric an s poonbill and the topic of A DO .NET is a trademark of O'Reilly & Ass oc iates, Inc. While every precaution has been taken in the preparation of this book, the publis her and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein. [ Team LiB ] 9 / 611 [ Team LiB ] Preface A lmost every software application is driven by data. Usually, this data is centralized in a relational databas e system such as SQ L Server, O racle, or DB2. In the .NET world, you access this information using Microsoft's lates t data access technology: A DO .NET. Like many other .NET technologies, A DO .NET bears some superficial similarities to its predecessor (in this cas e, ADO ). However, ADO .NET als o includes some dramatic changes and a few surpris ing innovations. It has a disconnected programming model tailored for distributed applications and the Web, built-in support for XML serialization, practical data binding, and an extensible set of interfaces that let you c reate custom data providers. Learning to use ADO .NET takes a little work, but the rewards are well worth it. With the help of this reference, you'll be up and running before you know it. [ Team LiB ] 10 / 611 [...]... define parameters for commands Implementing this interface is optional for an IDataAdapter-only provider IDataParameterCollection A llows a user to implement a parameter to a command and its mapping to DataSet columns IDataReader A read-only, forward-only stream of data from the data source A DataAdapter that populates a DataSet and reconciles any changes to the DataSet back to the data source IDataAdapter... source IDataAdapter This is the only interface required for every NET data provider implementation A DataAdapter for use with a relational database that inherits from IDataAdapter It populates a DataSet and reconciles any changes to the DataSet back to the data source IDbDataAdapter The NET Framework also includes a utility class called DbDataAdapter that can be inherited along with IDbDataAdapter, which... A llows constraints to be placed on data stored within a DataTable Unique and foreign key constraints can be created to maintain data integrity DataRelation Provides a way to indicate a relationship between different DataTable objects within a DataSet The DataRelation relates columns in the parent and child tables allowing navigation between the parent and child tables and referential integrity to be... columns in the table DataRow Corresponds to a row in a table and can examine and update data in the DataTable The DataTable exposes DataRow objects through the DataRowCollection object it contains The DataRow caches changes made to data contained in its columns, storing both original and current values This allows changes to be cancelled or to be later reconciled with the data source Constraint A llows... allow data to be retrieved from the data set, examined and modified offline, and reconciled with the data source through the DataAdapter: DataSet Provides a consistent way to deal with disconnected data completely independently of the data source The DataSet is essentially an in- memory relational database, serving as a container for the DataTable, DataColumn, DataRow, Constraint, and DataRelation objects... the data source can also be accessed not only with the O LE DB NET data provider but by any application or tool that supports O LE DB provider data access A custom NET data provider must at least support the DataSet through the IDataAdapter interface, and possibly the IDataParameter interface for parameterized queries Such a minimal data provider allows a DataSet to be loaded with data from the data source,... connecting to data sources as well as retrieving, manipulating, and updating data in both connected and disconnected environments [ Team LiB ] 19 / 611 [ Team LiB ] 1.1 ADO.NET Data Providers A n A DO NET data provider connects to a data source such as SQ L Server, O racle, or an O LE DB data source, and provides a way to execute commands against that data source in a consistent manner that is independent... supports input and output parameters as well as return values from stored procedures Transaction A llows transactions to be created on a connection so that multiple changes to data in a data source are treated as a single unit of work and either all committed or cancelled DataAdapter Bridges the data source and the disconnected DataSet or DataTable classes The DataAdapter wraps the connected classes to... IDbDataAdapter interface A custom adapter can provide access to data stored in a relational database It is important to remember that there are no constraints as to how the A DO NET disconnected classes are filled and how the changed data is updated back to the data source Consider a solution other than developing a custom NET data provider, if it is appropriate For more information about implementing... source, place that data into a DataSet, and subsequently update modifications to the DataSet back to the underlying data source Chapter 15 Describes how to commit updates made in a DataSet to the original data source Chapter 16 Describes how to start and manage client-initiated transactions, and compares them with stored procedure transactions and distributed CO M+ transactions Chapter 17 Explains how A DO . esp a ce Data Ada p ter Data Co lum nMa pping Data Co lum nMa pping C olle ction Data TableMapping Data TableMappingC o lle ctio n DbDa taAda pte r DBDa taP e rm issio. Providers A n ADO .NET data provider connects to a data source such as SQ L Server, Oracle, or an O LE DB data source, and provides a way to execute commands against that data source in a consistent manner. trademarks. Where those designations appear in this book, and O'Reilly & A ssociates, Inc. was aware of a trademark claim, the des ignations have been printed in caps or initial caps.