Designing .NET Class Libraries: Designing Progressive APIs (March 2, 2005)

Posted: Tuesday, March 10, 2005

Please note: Portions of this transcript have been edited for clarity

Introduction

frankred [MS] (Moderator):
Hello. Welcome to today’s chat on Designing Progressive APIs. Now, let’s introduce our knowledgeable experts...

Krzysztof Cwalina (Expert):
Hi, this is Krzysztof Cwalina. I am Program Manager on the CLR team responsible for the Design Guidelines. I welcome everybody to the chat session.

Joe Duffy [MS] (Expert):
Hey everyone. My name's Joe Duffy, and I work as a PM on the CLR team. I keep a blog at https://www.bluebytesoftware.com/blog/. Looking forward to the questions!

Kit George [MSFT] (Expert):
Hi, Kit George here, I am a Program Manager on the CLR, signing in from sunny, fun-filled Seattle, where there is no rain, it's a myth

BradA [MS] (Expert):
Hello from a Starbucks in Cary, NC!! Glad to join you...

Joe Duffy [MS] (Expert):
Kit lies. It rains all the time around here. ;)

Kit George [MSFT] (Expert):
Joe just jumps into the ocean and thinks that because he's wet, it must have rained ^o)

frankred [MS] (Moderator):
Alright, let the chatting begin... ;-)

Start of Chat

Krzysztof Cwalina (Expert):
Q: Given the post mortem of framework 1.1 and 1.0, are those shortcomings being addressed in framework 2.0 and winfx??
A: Yes, that's what we Program Managers do. When we start a new release cycle we look at feedback from all sorts of sources (internal and external customers, internet, etc.) and try to plan the next release based on the feedback. Do you have anything in particular in mind that you would like to give us feedback on?

Krzysztof Cwalina (Expert):
Q: Is there a formal process you use to create/design progressive APIs?
A: We try to make the "Designing Progressive API" lecture a part of the engineering culture at Microsoft. It takes time but we have made good progress. For example, all WinFx APIs need to go through a review and the first review sessions (early in the product cycle) are based on code samples showing how users would use these APIs.

Joe Duffy [MS] (Expert):
Q: Does Microsoft have any documentation on the rationale they use to design their own .NET centric APIs such as the CLR itself?
A: We do maintain a hefty set of Design Guidelines, which not only provide guidance on API design topics, but also the rationale on why the guidance is given. You can check out the v1.1 version here: https://msdn.microsoft.com/library/en-us/cpgenref/html/cpconNETFrameworkDesignGuidelines.asp. We (Brad, Krzys, and myself) post updates to our blogs as we are refining the docs. Along with the "Whidbey" (v2) release, we'll be updating the design guidelines on MSDN.

Kit George [MSFT] (Expert):
Q: With all the "bad" behaviors of the 1.x APIs, I understand you can't break legacy code, but how come you can't introduce fixed versions and put "Use this better version" links in the documentation for the 1.x versions?
A: Dustin, we can, and we do. We basically obsolete an old API and introduce a newer version of that same API, and the message for the obsolete attribute on the old API points you to the new one. This shows up when you try to compile code using the old API. But it is also fundamental that we not do this on a grand scale, since updating code, if it's an extensive process, is costly. The newer API must be sufficiently more valuable (either in correctness or capability) that we deem the overall win of adding thew replacement, better than the fact that we have two APIs that do very similar things (and the former API is now redundant). Brad actually has a really good blog on this issue: https://blogs.msdn.com/brada/archive/2004/11/22/267950.aspx

Krzysztof Cwalina (Expert):
Q: Are there examples where the framework wasn't developed with sample code in mind?
A: Oh yes, most of the Framework 1.0 (90%) was designed without starting with code samples. So, for example, 1.0 System.IO APIs had all the great functionality but it was quite difficult to actually use it especially from some languages that did not support certain language constructs (like assignment and boolean expression evaluation in a while loop). In 2.0, more and more APIs were designed with code samples in mind and I hope it will start showing in usability ratings.

Kit George [MSFT] (Expert):
Q: What part does UML play at Microsoft when designing an API if it is used at all?
A: Philip, this is up to individual product teams obviously, so it's impossible to speak for the company in general. For the CLR team, we tend not to use UML at all, even though we do have a defined process for development. We just don't tend to use UML methodologies or practices

BradA [MS] (Expert):
Q: Are there any books on API usability, progressive APIs etc.?
A: Funny you should ask... we are actually working on that now, but nothing to announce at this time... I hear that Yuval's book is good... https://www.amazon.com/exec/obidos/ASIN/0596003471/qid=1109798658/sr=2-1/ref=pd_ka_b_2_1/103-7027928-1817437

Joe Duffy [MS] (Expert):
Q: I Would like to know if you are considering unit test during api building?
A: Test is one of the major pillars of every product team. We use pretty extensive unit/integration test coverage as part of our development process. In fact, we have mandatory code coverage #s that we strive to meet.

Kit George [MSFT] (Expert):
Q: During the Everett release of the product, I suggested an experimental attribute. Something that we know will break but will let us play with different aspects of a platform (Xquery comes to mind). Any chance that can be revived?? I can think of several uses in relation to testing.
A: Douglas, I'd love to know more about what you're suggesting, probably the best way to make sure this gets logged is by adding it as a suggestion via the MSDN product feedback site. Note, we're solidly locked down for the upcoming Whidbey release, so suggestions are all for post-Whidbey releases. The problem with us providing such an attribute is that it might imply you should ship code with that attribute on the code, which doesn't sound like it would be the case (you should probably rip out such APIs for an official release). Furthermore, I'd love to know more about how you expect test teams to react to the attribute, and use it (what specific scenarios you envisage). MSDN feedback man, lay it on us!

Krzysztof Cwalina (Expert):
Q: Are there some best practice guidelines on when to seal a method/class?
A: Sealing methods is a good thing in general. Sealing classes is not a good thing in general (this is speaking about widely reusable frameworks). Virtual unsealed methods have very high design and test cost. Unsealed types without any virtual unsealed members can only be inherited from to add member, attributes, etc., which is a relatively small cost given the benefit of being able to add helper methods, add shorter constructors, etc.

Joe Duffy [MS] (Expert):
Q: What's the story with Environment.HasShutDownStarted? I can see it in Reflector/ILDASM, but I can't access it in C#!
A: This is actually one of the funniest mistakes we made in v1.0 (depending on who you talk to ;) ). In the Channel9 video here https://channel9.msdn.com/ShowPost.aspx?PostID=36366, Brian Grunkmeyer discusses this very problem. Basically, it was an instance property in v1.0, but unfortunately the Environment class is static (private ctor) and can't be instantiated!! So you can never get at it... well, without private reflection, of course. It was fixed in v1.1 and is now static. So you'll need to upgrade to get at it. In case you were searching for reasons to upgrade...

Kit George [MSFT] (Expert):
Q: Also, what's the deal with Environment.UserInteractive? Another crazy mistake by you guys? There's a ton of code there, but it always returns true?!
A: Yup, I think that was another item that we basically had a silly bug in: Environment wasn't our shining light in V1. Note that it's a whole lot better now.

frankred [MS] (Moderator):
Q: When will "Designing .NET Class Libraries: Designing Progressive APIs" be available for download rather than streaming?
A: Starting this Friday March 4, 1005. We are now making each presentation available for download the week after it is published online in streaming format.

Krzysztof Cwalina (Expert):
Q: What do you mean by progressive API?
A: Progressive means it’s easy to start using the API in simple scenarios and then gradually as the user gains expertise, they can program more and more advanced scenarios using the same API.

Krzysztof Cwalina (Expert):
Q: Wow. That's what you mean by progressive? Do you mean like remoting versus web services, where web services are built on top of remoting, so if you want to get very specific, you can use the remoting api?
A: I think the best example in the current framework is the System.Net namespace with the WebClient representing an easy way to start with APIs and then progress to the more advanced System.Net (socket) APIs.

Krzysztof Cwalina (Expert):
Q: Do you have a tutorial to help us understand the concept? I mean, you are teaching us to build an API to be increased in the future.
A: You mean a tutorial for the Progressive APIs design process. If yes, I expect to publish something on my blog https://blogs.msdn.com/kcwalina in 4-5 weeks. I have an internal draft ready.

Joe Duffy [MS] (Expert):
Q: Are there any special considerations you have to take when you want to expose your API for a SOA.
A: Usually when you talk about SOA, the granularity of the typical API is too fine to be given to a service operation. So, in most circumstances, you wouldn't want to "expose" an API through SOA. You'd want to write a facade that encapsulates some coarse grained action which performs multiple API calls to get the job done. I'd recommend "Patterns of Enterprise Application Architecture" https://www.amazon.com/exec/obidos/tg/detail/-/0321127420/qid=1109799111/sr=8-1/ref=sr_8_xs_ap_i1_xgl14/104-0548368-5407166?v=glance&s=books&n=507846 for guidance on messaging design.

Kit George [MSFT] (Expert):
Q: Are there any plans to make the CLR recompile-able (e.g. an open source architecture)?
A: At this stage, there really isn't. We are continuing to keep a close tab on expectations and activity in the open source domain, but we're pretty cautious in this arena, as a company. Note we are committed to providing you with an excellent user experience, and we will continue to look at what open source projects make sense to us. An example is Rotor.

Kit George [MSFT] (Expert):
Q: Kit - I didn't mean going open source as a company, just the ability to fix bugs in the CLR instead of having to wait for a year. No offence, but we all know 1.0 wasn't exactly the most stable API out there.
A: Yeah man, I understand. The answer is still no for now. There's a variety of reasons (for example, it introduces a big cost to servicing to take that kind of action. People have all manner of 'fixes' on their machine, and then call up PSS asking for support. Of course, it's really difficult for us to diagnose!), that contributes to us being really careful about doing that. But as noted, we do actively think about this.

Kit George [MSFT] (Expert):
Q: Speaking of rotor, any updates on 2.0??
A: I've got the Rotor guy (Joel Pobar) here in the room and the latest information is: 3-6 months after RTM ships. The best way to keep an eye on this is via posts on Joel's blog, such as: https://blogs.msdn.com/joelpob/archive/2003/12/12/53743.aspx

Kit George [MSFT] (Expert):
Q: Kit - I'm not trying to write a ballad about open source - I'm not an open source advocate - I am just curious if there are ANY talks about the customer being able to, as JS put it, decrate the CLR?
A: Nope. I'm not trying to give an official line or anything here either, but at this point in time, we've no plans to enable this.

Kit George [MSFT] (Expert):
Q: Kit. Having source-code and PDB is also good for debugging purposes. I haven't found any problems with the BCL, but have found lots on Windows Forms. Having the source code + symbols would have saved me enormous time.
A: Yup, a fair point man, and I know the WinForms team is looking at what they do in this space to help people out.

Krzysztof Cwalina (Expert):
Q: The vast wealth of information in the form of the application blocks are great for application development, are there any plans to provide similar blocks with API focus?
A: You mean blocks for reusable framework design? I would say that many of the BCL abstractions are such blocks. For example Stream, IEnumerable, TraceListener and many core BCL abstractions are to frameworks what application blocks are to applications.

Krzysztof Cwalina (Expert):
Q: What do you think of the API quality of the late-binding mechanisms used by the component model (e.g. how PropertyDescriptor.ResetValue uses reflection to look for ResetXXX)? Any plans for improvements here?
A: What improvements would you like to see? These APIs are mainly used at design time by tools (Visual Studio) and so we don't invest much in usability or perf (within reason) in such design-time only APIs.

Krzysztof Cwalina (Expert):
Q: "We don't invest much in (design time api) usability" - shame on them - quality is still quality no matter where it is. Where is their pride?
A: Oh, don't get me wrong. If we get feedback that quality is not there and people need it, we do invest. What I mean to say is that we would not invest to make design-time only APIs faster, because we would rather spend the resources making System.IO (for example) faster. Same with usability, we would rather spend resources making System.Windows.Forms APIs (used by millions of customers) more usable, instead of spending the resources on making design-time only APIs more usable.

Krzysztof Cwalina (Expert):
Q: "We don't invest much in (design time api) usability" - a basic piece of usability would have been the ability to highlight a chunk of HTML and automatically translate it into rendering code.
A: Please file the feature request at https://connect.microsoft.com/Main/content/content.aspx?ContentID=2220.

Joe Duffy [MS] (Expert):
Q: I haven't myself worked with 2.0, but has it updated its’ WebControls to work with other browsers besides Internet Explorer (IE)? Having an up-level browser supporting javascript (thinking validation controls), I do a lot of document data entry forms where this would be very helpful.
A: I'm not aware of ASP.NET WebControls that absolutely require IE to function properly. (Note: I'm not a self-professed ASP.NET expert, although I have worked with the technology quite a bit.) Most controls "light up" on IE, but in cases where that isn't possible, they will fall back to less fancy-shmancy implementation techniques, and in the worst case, rely on postbacks to take action. Do you have a specific control in mind that doesn't seem to be working? It's the responsibility of the control vendor, so I'm sure there are plenty of non-MS controls which don't work properly. Writing cross-browser JavaScript is obviously non-trivial in most cases.

Joe Duffy [MS] (Expert):
Q: With the api development in the dev team. How much are we going to see this move over to other teams. (Direct X, Office, etc) is this a CLR team -only focus or something that MS is trying to implement company-wide??
A: Developing new APIs/Frameworks is never a "development-only" task, but rather shared between the major pillars, i.e. Dev, PM, Test, UE, and Architecture. Of course this is a generalization, but this is the model we use for the .NET Framework, and every other team I've worked with here at MS use a similar model. We drive our standards across the company, and this course is actually one of the mechanisms we use to do that. People in Office, DX, etc. all know about these guidelines and try to be consistent with the Framework. But I wouldn't expect the .NET Framework to swallow up all managed API development, no, rather we're here to help, and lead by example.

frankred [MS] (Moderator):
Well. We’re out of time. I hope everyone had a good time and got answers to all of their questions. If you have more questions please visit the CLR team blogs https://msdn2.microsoft.com/netframework/aa569259.aspx section on the .NET Framework developer center. Please join us again next Wednesday for the next chat in the Designing .NET Class Libraries https://msdn2.microsoft.com/netframework/aa497250.aspx series.

Krzysztof Cwalina (Expert):
Thank you all for joining us today. I have to run, but if you have any additional questions related to Progressive APIs design, please email me kcwalina at mictosoft.com.

Top of page