Share via

Introducing the .NET Framework Standard Library Annotated Reference Vol1

  • Article

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.

Comments

  • Anonymous
    March 25, 2004
    Congratulations!,
    Can't wait to read it... :-)

  • Anonymous
    March 25, 2004
    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?

  • Anonymous
    March 25, 2004
    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.

  • Anonymous
    March 25, 2004
    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".

  • Anonymous
    March 25, 2004
    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.)

  • Anonymous
    March 25, 2004
    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.

  • Anonymous
    March 25, 2004
    "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? :)

  • Anonymous
    March 25, 2004
    The comment has been removed

  • Anonymous
    March 25, 2004
    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?

  • Anonymous
    March 25, 2004
    The comment has been removed

  • Anonymous
    March 25, 2004
    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

  • Anonymous
    March 25, 2004
    The comment has been removed

  • Anonymous
    March 26, 2004
    There is agreement among the BCL folks that ApplicationException was a mistake.

  • Anonymous
    March 26, 2004
    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

  • Anonymous
    March 27, 2004
    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.

  • Anonymous
    March 29, 2004
    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.

  • Anonymous
    March 31, 2004
    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 ?

  • Anonymous
    March 31, 2004
    Thanks for your comment Ben... There is a printed poster bound into the book that can easily be detached... does that help?

  • Anonymous
    March 09, 2006
    PingBack from http://www.thinksharp.org/2006/03/09/custom-exceptions/

  • Anonymous
    April 05, 2006
    TypesShouldNotExtendCertainBaseTypes fires on types that derive from ApplicationException and DoNotRaiseReservedExceptionTypes...

  • Anonymous
    October 12, 2006
    TypesShouldNotExtendCertainBaseTypes fires on types that derive from ApplicationException and DoNotRaiseReservedExceptionTypes

  • Anonymous
    May 11, 2007
    PingBack from http://shiftmode.com/2007/05/microsoft-changes-its-applicationexception-stance.html

  • Anonymous
    May 15, 2007
    While researching on Visual Studio Static Code Analysis topics I come over blog posts by Brad Abrams

  • Anonymous
    July 12, 2007
    PingBack from http://scottlaw.knot.org/blog/?p=218

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

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

  • Anonymous
    September 19, 2007
    Exception Best Practices - Say No To ApplicationException?

  • Anonymous
    January 19, 2008
    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

  • Anonymous
    February 14, 2008
    PingBack from http://mtrockcs.wordpress.com/2008/02/15/net-create-custom-exception-in-net/

  • Anonymous
    January 20, 2009
    PingBack from http://www.hilpers.com/261906-exception-gerne-will-ich-einem

  • Anonymous
    April 19, 2009
    PingBack from http://mrq.qbsoft.co.za/?p=23

  • Anonymous
    May 15, 2009
    PingBack from http://devlanfear.com/archives/892

  • Anonymous
    June 08, 2009
    PingBack from http://insomniacuresite.info/story.php?id=9175