Brad Abrams : Framework Design Guidelines

Video Posted for Belgium Visual Studio User’s Group: 10 Years of Framework Design Guidelines

BradA — Mon, 12 Oct 2009 00:34:55 GMT

As a nice follow up from my Belgium Visual Studio User’s Group: 10 Years of Framework Design Guidelines talk, I saw that they just posted the video (slides+audio).

Enjoy!

Oh, and i must include the shameless plug… Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries (2nd Edition)

Belgium Visual Studio User’s Group: 10 Years of Framework Design Guidelines

BradA — Mon, 28 Sep 2009 23:15:03 GMT

I had a great time at the the Belgium Visual Studio User’s Group meeting. The turn out was excellent. Thanks especially to Gill Cleeren and Pieter Gheysens for hosting it.

Gill asked me to talk about Framework Design Guidelines – I subject near and dear to my heart. I decided to do a bit of a look back over the last 10 years of framework design (we started what would later become the CLR about 10 years ago).. It is really fun to look at what has changed and what has not.

Thanks to the great folks at Addison-Wesley i was able to give away a few copies of the book as well.

Afterwards, we got to talking about how this stuff is actually the easy part of framework design. What is really hard is the social aspects. How do you get management bought into spending time on building shared components? how do you measure ROI in this space? Do investments in well designed, common frameworks pay off? What do you think? any positive or negative experiences?

Download the slide deck. I am told there is a video as well… I will post a link when I get it.

Anyway, here is the deck, enjoy. As I told someone at the event, plagiarism is the highest form of flattery.

Framework Design Guidelines Book: Extra Content from the DVD Posted

BradA — Thu, 02 Apr 2009 08:49:00 GMT

A few weeks ago a reader wrote in to tell me that they bought the Kindle version of the Framework Design Guidelines and was disappointed to not receive the DVD. Well, I was of course immediately jealous because I don’t have a kindle, but when I got over that, I ask the our excellent publishers and Addison-Wesley what we could do for our Kindle readers. To my (very pleasant) surprise, they suggested that we could just make all the DVD contents available for free on their website. So now, everyone on the internet gets this small dividend from the kindle!

Enjoy…

Download the entire DVD in one zip file. NOTE: The file is 2.34 GB in size. This includes a number of very helpful videos of presentations that cover much of the content of the book.

Download everything but the Presentations, which includes:

Framework Layering tools

TxRef tool for creating simple C# headerfile views of frameworks

Sample API Specification

Links to FxCop and Framework Design Studio

BTW – if you have liked the book, or have some feedback that may help other readers, I’d appreciate it if you wrote a quick review for Amazon. This helps customers more quickly find material they are interested in (or not).

Framework Design Guidelines: the System.* namespace

BradA — Fri, 27 Mar 2009 08:03:00 GMT

Today we have a guest post from Kit George who is the keeper of much of our internal Framework Design Guidelines. This is the stuff that Krys and I based a the book on. I asked Kit to post this internal information so you can get a feeling for what our guidelines are and why…. and so you can call us on it if we mess it up ;-)

As always, feedback and comments are welcome!

It is clear that there’s a bit of confusion over the namespace guidelines. Here is our attempt at make this clear. We know this will remain a contentious issue, but the goal of these guidelines is to clarify:

The .NET platform is not limited to any one single redistributable.
Types in the System.* namespace define the .NET platform. We of course carry existing types with us that go against this rule, but moving forward, we will adopt this approach
Something within Microsoft.* is produced by Microsoft but is not part of the .NET platform
APIs that are not necessarily going to be shipped are differentiable from APIs that are intended to be shipped

The .NET platform (which includes Silverlight, the full .NET Framework, the .NET Compact Framework, etc) continues to be that set of managed functionality, produced by Microsoft, that is for general application use. This doesn’t mean APIs that are guaranteed to be useful to every application (we can’t guarantee that), but APIs which can be used by many different application purposes and styles. These APIs may be shipped in different ways. There are other interesting questions that aren’t addressed by namespaces.

How does a user determine if an API is in Silverlight, but not in the .NET Framework 3.5? How does a user determine if an API is officially supported? How does a user determine if an API is usable on a device? These issues will be resolved using other mechanisms, not namespaces.

The following guidance comes out of this position and is used internally to help us follow the position.

Microsoft will use System.* for namespaces that are planned to be exposed publically and are considered part of the .NET platform.

Types that are part of the platform have expectations around quality, compatibility, consistency of design, and general usability. Types that are suitable for the platform portray the following characteristics:

We expect the API to be used by a wide variety of applications

Examples: string, central collections (List<T>, etc.), Linq, data

The API may be specific to a high level, but part of a general purpose application model (Label, TextBox, etc.)

Examples: Web, Windows.Forms, WPF

The API is formed of common abstractions and primitives that allow higher-level components to communicate

Examples: System.IO, System.Globalization

The API has had considerable design invested and is well-factored, reviewed, and consistent with the system. Depending on the ship vehicle, the size and deployment impact will have been considered

The API is finished and therefore, doesn’t require significant changes once publically available

Microsoft will use use Microsoft.* for namespaces that are planned to be shipped by the team and are considered application or non-platform components.

This applies to APIs/namespaces that are:

Part of an application. Applications are by definition, not useful to a variety of other scenarios/applications.

Example: Visual Studio, Office, SharePoint

Non-Core. Non-Core can be interpreted as ‘not for general Application use’. If you can’t see the API being used in most scenarios, or many application styles, it’s likely non-core. This includes APIs that serve a subset platform (for example, a common platform layer inside Office), APIs that are for a constrained task (such as MSBuild), or for a particular application type. This is NOT to say these cannot be moved/generalized in future versions if appropriate

Example: MSBuild, Office Infrastructure APIs

Microsoft will use Microsoft.Experimental.* for namespaces that are seeking consumer input, but have no committed ship plan

At Microsoft, In order to ship a CTP of a feature, a team and divisional commitment to officially productize the API is in place. Nothing is final, but the conviction and intent is there. Prior to this stage, there is literally no commitment or plans to ship the API. Use Microsoft.Experimental.* to communicate to customers that the feature in question is long-lead and may not see the light of day. Once the team is committed to shipping the API and is working on a schedule, feel free to use the most appropriate namespace based on the purpose of the productized type.

Avoid changing the namespace of a type once you’ve decided to ship the type publically (once you’ve reached the Beta stage).

Changing the namespace from a Beta onwards is costly to consumers. This issue is absolutely secondary to getting the namespace right, but consider the impact when making such decisions.

Framework Design Guidelines: LINQ Support

BradA — Tue, 10 Mar 2009 04:12:37 GMT

Continuing in our weekly blog post series that highlights a few of the new additions to the Framework Design Guidelines 2^nd edition.. This content is found in the LINQ section of Chapter 9: Common Design Patterns.

Supporting LINQ through IEnumerable<T>

DO implement IEnumerable<T> to enable basic LINQ support.

Such basic support should be sufficient for most in-memory data sets. The basic LINQ support will use the extension methods on IEnumerable<T> provided in the .NET Framework. For example, simply defineing as follows:

public class RangeOfInt32s : IEnumerable<int> {
public IEnumerator<int> GetEnumerator() {…}
IEnumerator IEnumerable.GetEnumerator() {…}
}

Doing so Allows for the following code, despite the fact that RangeOfInt32s did not implement a Where method:.

var a = new RangeOfInt32s();
var b = a.Where(x => x>10);

RICO MARIANI

Keeping in mind that you’ll get your same enumeration semantics, and putting a Linq façade on them does not make them execute any faster or use less memory.

Framework Design Guidelines: Dependency Properties

BradA — Tue, 03 Mar 2009 05:10:09 GMT

Continuing in our weekly blog post series that highlights a few of the new additions to the Framework Design Guidelines 2^nd edition.. This content is found in the Dependency Properties section of Chapter 9: Common Design Patterns. Phil offers some great additions to the base pattern.

The following guidelines describe details of Dependency Property dependency property design.

DO inherit from DependencyObject, or one of its subtypes, when implementing Dependency Properties. The type provides a very efficient implementation of a property store and automatically supports WPF data binding.

DO provide a regular CLR property and public static read-only field storing an instance of System.Windows.DependencyProperty for each Dependency Propertydependency property.

public class TextButton : DependencyObject {
   public string Text {
      get { return (string)this.GetValue(TextProperty); }
      set { this.SetValue(TextProperty,value); }
   }

   public static readonly DependencyProperty TextProperty =
      DependencyProperty.Register("Text",typeof(string),
           typeof(TextButton));
   }
}

DO implement Dependency Propertiesdependency properties by calling instance methods DependencyObject.GetValue and DependencyObject.SetValue.

public class TextButton : DependencyObject {
   public string Text {
      get { return (string)this.GetValue(TextProperty); }
      set { this.SetValue(TextProperty,value); }
   }
   public static readonly DependencyProperty TextProperty = …
}

DO name the Dependency Propertydependency property static field by suffixing the name of the property with “Property.”.

The first parameter to the DependencyProperty.Register method should be the name of the wrapper property.

public class TextButton : DependencyObject {
   public static readonly DependencyProperty TextProperty =
       DependencyProperty.Register("Text",typeof(string),
             typeof(TextButton));
}

Framework Design Guidelines: Factored Types

BradA — Tue, 24 Feb 2009 05:03:16 GMT

Continuing in our weekly blog post series that highlights a few of the new additions to the Framework Design Guidelines 2^nd edition.. This content is found in the Factored Types section of Chapter 9: Common Design Patterns. Phil offers some great additions to the base pattern.

PHIL HAACK

Since Factored Types have an explicit lifetime, it probably makes good sense to implement the IDisposable interface so that developers can make use of the using statement. The code sample here could then be refactored to:

using(SerialPort port = new SerialPort("COM1")) {
   port.Open();
   GZipStream compressed;
   compressed = new GZipStream(port.BaseStream,
      CompressionMode.Compress);
    compressed.Write(data, 0, data.Length);
}

Framework Design Guidelines: System.DBNull

BradA — Tue, 10 Feb 2009 04:56:00 GMT

Continuing in our weekly blog post series that highlights a few of the new additions to the Framework Design Guidelines 2^nd edition.. This content is found in the Nullable<T> section of Chapter 8: Usage Guidelines. Pablo helps us out with some subtle details that might really come in handy.

AVOID using System.DBNull. Prefer Nullable<T> instead.

PABLO CASTRO

Nullable<T> is in general a better representation of optional database values. One thing to consider though is that while Nullable<T> gives you the ability to represent null values, you don’t get database null operational semantics. Specifically, you don’t get null propagation through operators and functions. If you deeply care about the propagation semantics, consider sticking with DBNull.

Framework Design Guidelines: Overriding Object.ToString()

BradA — Tue, 03 Feb 2009 04:54:11 GMT

Continuing in our weekly blog post series that highlights a few of the new additions to the Framework Design Guidelines 2^nd edition.. This content is found in the Object.ToString section of Chapter 8: Usage Guidelines. Christophe provides some great implementation tips for these guidelines.

DO try to keep the string returned from ToString short.

The debugger uses ToString to get a textual representation of an object to be shown to the developer. If the string is longer than the debugger can display (typically less than one screen length), the debugging experience is hindered.

CHRISTOPHE NASARRE

In term of debugging experience, you should decorate your type with DebuggerDisplayAttribute in addition to overriding ToString for that particular purpose.

DO string formatting based on the current thread culture when returning culture-dependent information.

CHRISTOPHE NASARRE

To be more explicit, use the CultureInfo instance returned by a thread’s CurrentCulture property to format any numeric or date, and the one returned by CurrentUICulture to look up any resource. People are often confused between the two properties.

.NET Fireside Chats - Brad Abrams and Krzysztof Cwalina

BradA — Wed, 28 Jan 2009 06:52:57 GMT

The .NET Zone just published an interview with Kry and me. Check it out:

.NET Fireside Chats - Brad Abrams and Krzysztof Cwalina

You can learn some interesting stuff about what lead to writing the first edition of the book, what a 'Framework' is and what the hardest framework design problems are.

I'd love to hear your feedback and thoughts

Oh, and they published a sample section of the book for free in PDF format. This is from Chapter 9 and covers LINQ guidelines.

Enjoy!

Framework Design Guidelines: Avoiding custom delegates

BradA — Tue, 27 Jan 2009 04:49:55 GMT

Continuing in our weekly blog post series that highlights a few of the new additions to the Framework Design Guidelines 2nd edition.. This content is found in the Events and Callbacks section of Chapter 6: Designing for Extensibility. I am impressed by how simple new additions to the BCL can have such a large (and positive) effect on framework design. As these new advances come out, learn them and use them!

DO use the new Func<…>, Action<…>, or Expression<…> instead of custom delegates, when defining APIs with callbacks.

Func<…> and Action<…> represent generic delegates. The following is how .NET Framework defines them:

public delegate void Action()
public delegate void Action<T1, T2>(T1 arg1, T2 arg2)
public delegate void Action<T1, T2, T3>(T1 arg1, T2 arg2, T3 arg3)
public delegate void Action<T1, T2, T3, T4>(T1 arg1, T2 arg2, T3 arg3, T4 arg4)
public delegate TResult Func<TResult>()
public delegate TResult Func<T, TResult>(T arg)
public delegate TResult Func<T1, T2, TResult>(T1 arg1, T2 arg2)
public delegate TResult Func<T1, T2, T3, TResult>(T1 arg1, T2 arg2, T3 arg3)
public delegate TResult Func<T1, T2, T3, T4, TResult>(T1 arg1, T2 arg2, T3 arg3, T4 arg4)

They can be used as follows:

Func<int,int,double> divide = (x,y)=>(double)x/(double)y;
Action<double> write = (d)=>Console.WriteLine(d);
write(divide(2,3));

Expression<…> represents function definitions that can be compiled and subsequently invoked at runtime but can also be serialized and passed to remote processes. Continuing with our example:

Expression<Func<int,int,double>> expression =(x,y)=>(double)x/(double)y;
Func<int,int,double> divide = expression.Compile();
write(divide2(2,3));

Notice how the syntax for constructing an Expression<> object is very similar to the one used to construct a Func<> object; in fact, the only difference is the static type declaration of the variable (Expression<> instead of Func<>).

RICO MARIANI

Most times you’re going to want Func or Action if all that needs to happen is to run some code. You need Expression when the code needs to be analyzed, serialized, or optimized before it is run. Expression is for thinking about code, Func/Action is for running it.

Framework Design Guidelines: Sealed Classes

BradA — Tue, 20 Jan 2009 06:10:25 GMT

Continuing in our weekly blog post series that highlights a few of the new additions to the Framework Design Guidelines 2^nd edition.. This content is found in the Extensibility Mechanisms section of Chapter 6: Designing for Extensibility. It is interesting to watch as new development methodologies become more popular and how the color the guidelines…

CONSIDER using unsealed classes with no added virtual or protected members as a great way to provide inexpensive yet much appreciated extensibility to a framework.

Developers often want to inherit from unsealed classes so as to add convenience members such as custom constructors, new methods, or method overloads. For example, System.Messaging.MessageQueue is unsealed and thus allows users to create custom queues that default to a particular queue path or to add custom methods that simplify the API for specific scenarios (in the following example, the scenario is for a method sending Order objects to the queue).

public class OrdersQueue : MessageQueue {
   public OrdersQueue() : base(OrdersQueue.Path){
      this.Formatter = new BinaryMessageFormatter();
   }

   public void SendOrder(Order order){
      Send(order,order.Id);
   }
}

PHIL HAACK

Because Test Driven Development has caught fire in the .NET Developer community, many developers want to inherit from unsealed classes (often dynamically using a mock framework) in order to substitute a test double in the place of the real implementation.

At the very least, if you’ve gone to the trouble of making your class unsealed, consider making key members virtual, perhaps via the Template Method Pattern, in order to provide more control.

Framework Design Guidelines: Extension Methods

BradA — Tue, 13 Jan 2009 06:07:24 GMT

Continuing in our weekly blog post series that highlights a few of the new additions to the Framework Design Guidelines 2^nd edition.. This content is found in the Extension Methods section of Chapter 5: Member Design. One of the major new features we added to the Framework recently is extension methods. While this a very powerful new feature, it does come with some new responsibility.

CONSIDER using extension methods in any of the following scenarios:

To provide helper functionality relevant to every implementation of an interface, if said functionality can be written in terms of the core interface. This is because concrete implementations cannot otherwise be assigned to interfaces. For example, the LINQ to Objects operators are implemented as extension methods for all IEnumerable<T> types. Thus, any IEnumerable<> implementation is automatically LINQ-enabled.
When an instance method would introduce a dependency on some type, but such a dependency would break dependency management rules. For example, a dependency from String to System.Uri is probably not desirable, and so String.ToUri() instance method returning System.Uri would be the wrong design from a dependency management perspective. A static extension method Uri.ToUri(this string str) returning System.Uri would be a much better design.

RICO MARIANI

The value of this cannot be overstated. Extension methods provide you with a way to give interfaces not just one default implementation but as many as you need, and you can choose between them simply by bringing the right namespace(s) into your lexical scope with using. However, this could be easily abused in the same way that complex #include combinations in C++ can make the final code hard to read.

Another interesting feature of this manner of adding functionality to a class is that you could potentially partition (extension) methods of the same class into different assemblies for performance reasons. Again, this should not be done lightly, because you could cause great confusion.

This is one of the many times I like to quote from Spiderman – “With great power comes great responsibility.”

PHIL HAACK

Section 2.2.4.1 covers the topic of layering in namespaces, which I think applies well to extension methods.

One scenario I’ve seen is to put functionality that is more advanced or esoteric in a separate namespace. That way, for core scenarios, these extra methods do not “pollute” the API. But for those who know about the namespace, or need these alternate scenarios, they can add the namespace and gain access to these extra methods.

The drawback, of course, is that this results in a “hidden” API that is not very discoverable.

JOE DUFFY

Extension methods can also be used to provide actual concrete method implementations for interfaces. For example, if you ship an IFoo interface, you can also have a static Foo class with a method public static void Bar(this IFoo f) that makes all instances of IFoo effectively have an extra Bar method.

Framework Design Guidelines: An appeal for consistency

BradA — Tue, 16 Dec 2008 06:03:01 GMT

Continuing in our weekly blog post series that highlights a few of the new additions to the Framework Design Guidelines 2^nd edition.. This content is found in the Names of Classes, Structs, and Interfaces section of Chapter 3: Naming Guidelines. Even in the .NET Framework we don’t always apply the design guidelines consistently – and, as Phil found out, we often pay the price for it.

DO ensure that the names differ only by the “I” prefix on the interface name when you are defining a class–interface pair where the class is a standard implementation of the interface.

The following example illustrates this guideline for the interface IComponent and its standard implementation, the class Component:

public interface IComponent { … }

public class Component : IComponent { … }

PHIL HAACK

One place where the framework violates this convention is the class HttpSessionState, which you would suspect implements IHttpSessionState, but you’d be wrong, as I was.

This inconsistency nearly bit us when we were developing our HttpContextBase abstraction of HttpContext, because it seemed we could expose the Session property as the IHttpSessionState interface, which turned out to not be the case.

Framework Design Guidelines: Naming New Versions of Existing APIs

BradA — Tue, 09 Dec 2008 05:57:50 GMT

Continuing in our weekly blog post series that highlights a few of the new additions to the Framework Design Guidelines 2^nd edition.. This content is found in the Naming New Versions of Existing APIs of Chapter 3: Naming Guidelines. Incrementally evolving an existing, popular API is very hard. My main take away personally from this guidelines (and Kit’s annotation) is to work hard to get it right the first time!

DO use the “64” suffix when introducing versions of APIs that operate on a 64-bit integer (a long integer) instead of a 32-bit integer. You only need to take this approach when the existing 32-bit API exists; don’t do it for brand new APIs with only a 64-bit version.

For example, various APIs on System.Diagnostics.Process return Int32 values representing memory sizes, such as PagedMemorySize or PeakWorkingSet. To appropriately support these APIs on 64-bit systems, APIs have been added that have the same name but a “64” suffix.

public class Process {
   // old APIs
   public int PeakWorkingSet { get; }
   public int PagedMemorySize { get; }

// …
// new APIs

public long PeakWorkingSet64 { get; }
public long PagedMemorySize64 { get; }
}

KIT GEORGE

Note that this guideline applies only to retrofitting APIs that have already shipped. When designing a brand new API, use the most appropriate type and name for the API that will work on all platforms, and avoid using both “32” and “64” suffixes. Consider using overloading.