Introducing the .NET Framework Standard Library Annotated Reference Vol1


I am very happy to have this book done!   Ever since I started working on the CLR, almost 6 years ago, I have wanted SOMEONE to do a book like this.  In a past life when I did Java development, I really liked Chan (et al)’s The Java Class Libraries, Volume 1 and I wanted a similar book covering the BCL.   At the time I didn’t think I would be the editor. This book could have never come together without significant help from a large number of folks.  I will not repeat the book’s acknowledgements here, but know that it is more their work than mine.


 


So, consider this the first plug for the .NET Framework Standard Library Annotated Reference Vol 1 (I think this needs a shorter name, how about SLAR)?


 


This book is based on the text from ECMA\ISO CLI and C# standards.  In addition, we included a number of features to make it valuable to the average developer. 


Samples – Over 1,000 additional samples showing how to use the APIs (all available on the CD)


Annotations – Personal comments from key members of the BCL design team.  These were fun and therapeutic for us to write.  I hope when you read them you get a sense for the personalities inside the BCL team as well as some insights into what we did well, what we could have done better and how best to use what we produced. 


Poster and Diagrams – We show clearly and visually how the BCL is put together. 


“C# Header file” view of each type – This is exactly the view we use when we are designing and reviewing types internally, so we thought it would be useful to developers as well.  We also indicate which members are not in the .NET Compact Framework, those that were introduced in V1.1 of the .NET Framework and those that are not part of the Standard.


 


Over the next few months, my intention is to share some of that content with you on this blog.  I am not trying to turn this blog into an ad for the book.  In fact, I don’t even get royalties on the thing.  My goal in writing the book and this blog is the make developers on our platform happier and more productive.    Although if you do buy a copy or two it will help my case to produce volume II, update for Whidbey\Longhorn, etc.


 


Here is the first type in the book and a couple of annotations:


 


 


public class ApplicationException : Exception


{


        // Constructors


        public ApplicationException ();


        public ApplicationException (string message);


        public ApplicationException (string message, Exception innerException);


MS CF   protected ApplicationException (SerializationInfo info, StreamingContext context);


}


 


 


KCDesigning exception hierarchies is tricky. Well-designed exception hierarchies are wide, not very deep, and contain only those exceptions for which there is a programmatic scenario for catching. We added ApplicationException thinking it would add value by grouping exceptions declared outside of the .NET Framework, but there is no scenario for catching ApplicationException and it only adds unnecessary depth to the hierarchy.


 


JRYou should not define new exception classes derived from Application-


Exception; use Exception instead. In addition, you should not write code that


catches ApplicationException.


 


 

Comments (53)

  1. Corrado Cavalli says:

    Congratulations!,

    Can’t wait to read it… :-)

  2. Eric says:

    Wait, I’m confused. I thought the whole point of ApplicationException was to serve as a base for all application-specific exceptions… All of the Microsoft examples for custom exceptions (including this one: http://msdn.microsoft.com/msdnmag/issues/02/11/NETExceptions/default.aspx) inherit from ApplicationException. Is JR’s annotation incorrect, or are all of the examples wrong?

  3. Don says:

    I’m confused. Are these comments indended for the programming public, or microsoft employees? I thought ALL custom exceptions should inherit from ApplicationException and you should never write code to catch Exception.

  4. Brad,

    How about sharing the TOC from the book. As soon as I read your blog entry I clicked on over to Amazon to purchase it, but was confused by the title:

    .NET Framework Standard Library Annotated Reference, Volume 1: Base Class Library and Extended Numerics Library, 1/e

    I’m not exactly sure what Vol 1 covers. You stated that Vol 2 would be an update for Whidbey/Longhorn, but the title for Vol 1 dosent sound like it has everything "pre-whidbey".

  5. Martin Liversage says:

    When first reading Mr. Richters advice on not using ApplicationException I was stunned, but it actually make sense. If you create some application specific exceptions you may want to derive these exceptions from a common base class in order to be able to catch them all in a single catch clause. Deriving this common exception from ApplicationException doesn’t add anything useful to your exception hierarchy – it just deepens it. Off course, you may also want to use a library you have written providing a different set of exceptions, but you rarely want to treat these exceptions in the same way as you treat your application exceptions. Except in cases where there is some form of coupling, but then you need to consider that in your exception design. I now realize that ApplicationException doesn’t add anything useful to the mix.

    I’m sure that Mr. Abrams selected the ApplicationException sample not because it is the first in the book, but because Mr. Richters annotation can be seen as "sensational" and it will attract a lot of attention to this blog entry. :^) I can already see the /. headline: .NET guru uncovers huge flaw in MS coding guidelines (just kidding.)

  6. Darrell says:

    Roy – he didn’t say Vol 2 would be an update for Whidey/Longhorn. He said sales "will help my case to produce volume II, update for WhidbeyLonghorn, etc." The commas mean Vol 2, and/or Whidbey update, and/or Longhorn update, etc.

  7. Eric says:

    "When first reading Mr. Richters advice on not using ApplicationException I was stunned, but it actually make sense. If you create some application specific exceptions you may want to derive these exceptions from a common base class in order to be able to catch them all in a single catch clause. Deriving this common exception from ApplicationException doesn’t add anything useful to your exception hierarchy – it just deepens it."

    That’s true, and it certainly makes sense (my custom exceptions are all inherited from a single application base exception class) — I’m just confused as to why <strong>every single example</strong> Microsoft has put out — in the MCSD books, in the MSDN samples, in the very documentation for the ApplicationException class — says that ApplicationException should always be the base class for all custom exceptions. It’s a simple change to make if you have a single custom exception base class (you just change its inheritance to System.Exception instead of System.ApplicationException and voila), but given that it’s such a simple change I have no idea why this hasn’t been changed in any of the docs, even for 1.1. Will the docs reflect this in 2.0, or is this some super secret initiation ritual to prove you’re not a .Net newbie? :)

  8. Darrell..

    You are correct, I had mis-read that. Thanks for pointing that out. But the idea behind the post stands (the TOC, and just what is actually covered in the book).

    I hate getting "Vol ??" type books until all the volumns are available, unless the volums are seperated on a specific line (Vol 1 – WinForms, Vol 2 – .NET CF, Vol 3 – ASP.NET, ect).

  9. Ivan Towlson says:

    Brad, what is the balance between the "here are the types and signatures and code fragments" stuff and the annotations or behind-the-scenes insights? The latter sound useful and interesting, but I already have the former in MSDN. Put another way, how much of the book is "added value" over the main Framework documentation?

  10. Brad Abrams says:

    Thanks for all the comments on the book, I can already see that this book is going to be a fun source of blogging fodder! I tried to maintain a very minium level of editorial discretion on the annotations. My goal was to get folks that were heavily involved in the design of the BCL to comment candidly from their point of view. There are no annotations that are wrong technically, but that does not mean they are all the Microsoft official postion.

    That said, I happen to agree with Jeff on ApplicationException. IMHO, the biggest problem is there is such a fine line between applications and libraries and that line will get more fuzzy overtime. Is Word an application or a library? There is nothing that will break if you inherit from ApplicationExeption, but it is also true that nothing in the system depends on Exceptions driving from ApplicationException. Martin Liversage sums it up well, ApplicationException just does not provide a much value.

    As for the TOC, I will get that posted soon (I am actually OOF on vacation right now)

    Right – Vol2 will cover the Xml, Reflection and Runtime Infrastructure libraries.

    Ivan, There are around 100 annotations in the book and a TON of samples we added over and above what is in the standarddocs. You may find this isn’t trye for you, but I have found the page layout, diagrams, ILASM signatures, etc do at significant value as well.

    Oh, yes, someone on my team suggested I included this books Amazon sales rank with each post so we can track it overtime. It was ~3,000 when I did the original post.

    Current Amazon Sales Rank: 1,026

  11. Brad Abrams says:

    In lieu of the full TOC, I thought just a list of the types covered in Vol1 would help folks. Does that help?

    System.ApplicationException

    System.ArgumentException

    System.ArgumentNullException

    System.ArgumentOutOfRangeException

    System.ArithmeticException

    System.Array

    System.ArrayTypeMismatchException

    System.AsyncCallback

    System.Attribute

    System.AttributeTargets

    System.AttributeUsageAttribute

    System.Boolean

    System.Byte

    System.Char

    System.CharEnumerator

    System.CLSCompliantAttribute

    System.Collections.ArrayList

    System.Collections.Comparer

    System.Collections.DictionaryEntry

    System.Collections.Hashtable

    System.Collections.ICollection

    System.Collections.IComparer

    System.Collections.IDictionary

    System.Collections.IDictionaryEnumerator

    System.Collections.IEnumerable

    System.Collections.IEnumerator

    System.Collections.IHashCodeProvider

    System.Collections.IList

    System.Console

    System.Convert

    System.DateTime

    System.Decimal

    System.Delegate

    System.Diagnostics.ConditionalAttribute

    System.DivideByZeroException

    System.Double

    System.DuplicateWaitObjectException

    System.Enum

    System.Environment

    System.EventArgs

    System.EventHandler

    System.Exception

    System.ExecutionEngineException

    System.FlagsAttribute

    System.FormatException

    System.GC

    System.Globalization.DateTimeFormatInfo

    System.Globalization.DateTimeStyles

    System.Globalization.NumberFormatInfo

    System.Globalization.NumberStyles

    System.Globalization.UnicodeCategory

    System.IAsyncResult

    System.ICloneable

    System.IComparable

    System.IDisposable

    System.IFormatProvider

    System.IFormattable

    System.IndexOutOfRangeException

    System.Int16

    System.Int32

    System.Int64

    System.InvalidCastException

    System.InvalidOperationException

    System.InvalidProgramException

    System.IO.Directory

    System.IO.DirectoryNotFoundException

    System.IO.EndOfStreamException

    System.IO.File

    System.IO.FileAccess

    System.IO.FileLoadException

    System.IO.FileMode

    System.IO.FileNotFoundException

    System.IO.FileShare

    System.IO.FileStream

    System.IO.IOException

    System.IO.MemoryStream

    System.IO.Path

    System.IO.PathTooLongException

    System.IO.SeekOrigin

    System.IO.Stream

    System.IO.StreamReader

    System.IO.StreamWriter

    System.IO.StringReader

    System.IO.StringWriter

    System.IO.TextReader

    System.IO.TextWriter

    System.MarshalByRefObject

    System.Math

    System.NotFiniteNumberException

    System.NotSupportedException

    System.NullReferenceException

    System.Object

    System.ObjectDisposedException

    System.ObsoleteAttribute

    System.OutOfMemoryException

    System.OverflowException

    System.Random

    System.RankException

    System.SByte

    System.Security.CodeAccessPermission

    System.Security.IPermission

    System.Security.Permissions.CodeAccessSecurityAttribute

    System.Security.Permissions.EnvironmentPermission

    System.Security.Permissions.EnvironmentPermissionAccess

    System.Security.Permissions.EnvironmentPermissionAttribute

    System.Security.Permissions.FileIOPermission

    System.Security.Permissions.FileIOPermissionAccess

    System.Security.Permissions.FileIOPermissionAttribute

    System.Security.Permissions.PermissionState

    System.Security.Permissions.SecurityAction

    System.Security.Permissions.SecurityAttribute

    System.Security.Permissions.SecurityPermission

    System.Security.Permissions.SecurityPermissionAttribute

    System.Security.Permissions.SecurityPermissionFlag

    System.Security.PermissionSet

    System.Security.SecurityElement

    System.Security.SecurityException

    System.Security.VerificationException

    System.Single

    System.StackOverflowException

    System.String

    System.SystemException

    System.Text.ASCIIEncoding

    System.Text.Decoder

    System.Text.Encoder

    System.Text.Encoding

    System.Text.StringBuilder

    System.Text.UnicodeEncoding

    System.Text.UTF8Encoding

    System.Threading.Interlocked

    System.Threading.Monitor

    System.Threading.SynchronizationLockException

    System.Threading.Thread

    System.Threading.ThreadAbortException

    System.Threading.ThreadPriority

    System.Threading.ThreadStart

    System.Threading.ThreadState

    System.Threading.ThreadStateException

    System.Threading.Timeout

    System.Threading.Timer

    System.Threading.TimerCallback

    System.Threading.WaitHandle

    System.TimeSpan

    System.Type

    System.TypeInitializationException

    System.UInt16

    System.UInt32

    System.UInt64

    System.UnauthorizedAccessException

    System.ValueType

    System.Version

  12. Darrell says:

    Roy – yeah, I agree. I like buying Volume 1-x all at the same time. For example, the Essential .NET Vol 1 with Don Box, where’s Vol 2, huh?

  13. Ken Brubaker says:

    There is agreement among the BCL folks that ApplicationException was a mistake.

  14. Dag König says:

    Han har precis släppt en ny tjock bok som jag direkt beställde ifrån Amazon. .NET Framework Standard Library Annotated Reference Vol 1, heter den. Vilken titel. Mums. Introducing the .NET Framework Standard Library Annotated Reference Vol1

  15. Brad – The list you posted is should be fine instead of the TOC. That, along with your other post about what is/may be planned for vol 2 is enough for me to purchase it.

    Darrell – Yea. I have that one as well. I guess I am that way because the company I used to work for (TurboPower Software) wrote a library once (Essentials, Vol I) with every intention of doing more, but never did. It turned into a running joke in the company.

  16. Avery Moore says:

    Congrats on the book. The The Java Class Libraries, Volume 1 used to be one of my favorite java references from back in my java days.

  17. Ben says:

    Why can’t you print the poster that comes as a PDF on the accompanying CD? The book I can obviously understand 😉 but the poster ?

  18. Brad Abrams says:

    Thanks for your comment Ben… There is a printed poster bound into the book that can easily be detached… does that help?

  19. TypesShouldNotExtendCertainBaseTypes fires on types that derive from ApplicationException and DoNotRaiseReservedExceptionTypes…

  20. TypesShouldNotExtendCertainBaseTypes fires on types that derive from ApplicationException and DoNotRaiseReservedExceptionTypes

  21. While researching on Visual Studio Static Code Analysis topics I come over blog posts by Brad Abrams

  22. Joel Ross says:

    Exception Best Practices – Say No To ApplicationException?

  23. Mainz says:

    Contrary to common belief, creating reliable, robust software is not something near to impossible. Notice that I’m not referring to bug-free software, intended to control nuclear power plants. I’m referring to common business software, which can run unattended