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);

}

 

 

KC - Designing 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.

 

JR - You should not define new exception classes derived from Application-

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

catches ApplicationException.

 

 

Published 25 March 04 12:12 by BradA
Filed under: ,

Comments

# Corrado Cavalli said on March 25, 2004 12:23 PM:
Congratulations!,
Can't wait to read it... :-)

# Eric said on March 25, 2004 12:49 PM:
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?
# Don said on March 25, 2004 12:50 PM:
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.

# Roy J. Salisbury @ VsDevCentral said on March 25, 2004 1:29 PM:
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".

# Robert Hurlbut's .Net Blog said on March 25, 2004 5:03 PM:
# Martin Liversage said on March 25, 2004 2:07 PM:
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.)
# Darrell said on March 25, 2004 2:14 PM:
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 Whidbey\Longhorn, etc." The commas mean Vol 2, and/or Whidbey update, and/or Longhorn update, etc.
# Eric said on March 25, 2004 2:28 PM:
"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? :)
# Roy J. Salisbury @ VsDevCentral said on March 25, 2004 3:28 PM:
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).
# Andrew Stopford's Weblog said on March 25, 2004 6:48 PM:
# Ivan Towlson said on March 26, 2004 1:10 AM:
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?
# Brad Abrams said on March 26, 2004 4:56 AM:
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 standard\docs. 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
# Brad Abrams said on March 26, 2004 5:06 AM:
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
# Ken Brubaker said on March 26, 2004 8:45 AM:
There is agreement among the BCL folks that ApplicationException was a mistake.
# Darrell said on March 26, 2004 6:13 AM:
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?
# Dag König said on March 26, 2004 2:02 PM:
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
# Mark Treadwell said on March 26, 2004 11:10 PM:
# Roy J. Salisbury @ VsDevCentral said on March 27, 2004 1:01 PM:
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.
# Avery Moore said on March 29, 2004 12:33 PM:
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.
# Ben said on April 1, 2004 1:21 AM:
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 ?
# Brad Abrams said on April 1, 2004 7:23 AM:
Thanks for your comment Ben... There is a printed poster bound into the book that can easily be detached... does that help?
# Mark Treadwell said on April 1, 2004 9:28 PM:
# Brad Abrams said on April 6, 2004 10:04 PM:
# Brad Abrams said on April 8, 2004 12:48 AM:
# Eli Robillard's World of Blog. said on May 10, 2004 1:10 PM:
# Mark Treadwell said on May 18, 2004 9:16 PM:
# Mark Treadwell said on May 18, 2004 9:23 PM:
# jaybaz_MS's WebLog said on May 21, 2004 9:58 PM:
# Lance's Whiteboard said on August 17, 2004 7:58 PM:
# Blogging About .NET said on November 4, 2004 9:15 AM:
# Eric Gunnerson's C# Compendium said on November 19, 2004 4:44 AM:
# Eric Gunnerson's C# Compendium said on November 23, 2004 2:07 PM:
# Brad Abrams said on January 7, 2005 10:55 AM:
# Edward Ferron's WebLog said on February 8, 2005 8:19 AM:
# Brad Abrams said on February 11, 2005 9:23 AM:
# Rolando Ramirez's WebLog said on April 11, 2005 10:28 AM:
# Rolando Ramirez's WebLog said on April 11, 2005 10:33 AM:
# .NET Hobbyist Programmer said on July 9, 2005 11:21 PM:
# ThinkSharp.org » Blog Archive » Custom Exceptions and Serialization. said on March 10, 2006 7:24 AM:
PingBack from http://www.thinksharp.org/2006/03/09/custom-exceptions/
# Visual Studio Managed Code Analysis (FxCop) said on April 5, 2006 11:31 PM:
TypesShouldNotExtendCertainBaseTypes fires on types that derive from ApplicationException and DoNotRaiseReservedExceptionTypes...
# Visual Studio Managed Code Analysis (FxCop) said on October 12, 2006 12:52 PM:

TypesShouldNotExtendCertainBaseTypes fires on types that derive from ApplicationException and DoNotRaiseReservedExceptionTypes

# shiftMode » Blog Archive » Microsoft changes it’s ApplicationException stance said on May 11, 2007 11:49 AM:

PingBack from http://shiftmode.com/2007/05/microsoft-changes-its-applicationexception-stance.html

# knom's developer corner said on May 15, 2007 8:42 AM:

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

# Scott’s Blog » Don’t Derive from ApplicationException said on July 13, 2007 7:50 AM:

PingBack from http://scottlaw.knot.org/blog/?p=218

# Thachvv’s Weblog Exception Handling Best Practices in .NET « said on August 5, 2007 12:15 PM:

PingBack from http://thachvv.wordpress.com/2007/08/05/exception-handling-best-practices-in-net/

# Thachvv’s Weblog Creating Custom Exceptions in .NET « said on August 5, 2007 1:10 PM:

PingBack from http://thachvv.wordpress.com/2007/08/05/creating-custom-exceptions-in-net/

# Joel Ross said on September 19, 2007 9:19 PM:

Exception Best Practices - Say No To ApplicationException?

# Mainz said on January 20, 2008 4:18 AM:

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

# [.NET] Create custom Exception in .NET « MtRock.cs Paradise 16 said on February 15, 2008 2:10 AM:

PingBack from http://mtrockcs.wordpress.com/2008/02/15/net-create-custom-exception-in-net/

New Comments to this post are disabled

Search

Go

This Blog

本博客中文版 (View in Chinese)



These postings are provided "AS IS" with no warranties, and confer no rights.

Syndication

Page view tracker