locked
Upgrade Reference Tables RRS feed

  • General discussion

  • This was my best guess at where to post this recommendation.  Hopefully it'll get forwarded if appropriate.

    .NET 4.0 is now the 6th(?) version of .NET?  I think what would be of immense use for busy .NET developers is a summary table that lists all the classes in the base class library, and the .NET version in which each class was introduced.  This table should then be kept updated for future versions.

    There are various posts on the web that mention "the big stuff" that was introduced in each version.  To give one example, the PrintPort class (and its kin) appeared in 3.0.  Because they weren't "the big stuff", as far as I can tell they didn't get any fanfair.  It's understandable that PrintPort and its kin weren't exactly the big lead story of the day, but for some of us developers they were VERY important new classes.

    Since classes are also "enhanced" with new .NET versions, the table should probably also provide some indication of when a class was enhanced with something new.  The table would definitely NOT attempt to give any information about the classes or their enhancements.  That's what hyperlinks are for.  Click on the class name and it'll take you to the reference documentation for the class.
    -- kburgoyne
    Saturday, February 13, 2010 6:11 PM

All replies

  • Hello kburgoyne,

    This is interesting suggestion, however I don't fully understand value of this for .NET developers. Therefore let me ask you couple of additional questions:

    1) Each class has information about when it was introduced on MSDN - the 'This pase is specific to' section or 'Version Information' section (e.g. http://msdn.microsoft.com/en-us/library/system.printing.printport.aspx). Why is this not sufficient?
    Is it because you would like to see information for all classes in one file for some automation? What kind of automation then?
    Is it because you would like to see list of all changes in new .NET Fx version, so you can use them all ASAP?

    Anyway I believe it should be fairly simple to create a Reflection-based tool which would compare 2 versions of the same assembly (or set of assemblies) to list all new classes. (That should take care of the automation case at least)

    2) Enhancements ... What kind of enhancements would you like to see mentioned? New public methods/properties/events? (That should be doable with the above Reflection-based tool approach)
    What about significant breaking changes in method behaviors? What about less significant changes? (Those would be quite difficult to capture in such list)

    Thanks,
    -Karel
    Saturday, February 13, 2010 9:23 PM
    Moderator
  • Hi Karel,

    Thanks for the reply and inquiry.  I totally agree that the MSDN documentation is really excellent and does an excellent job of including version information for each class.  Your comments about being able to generate such a list using automation is also why I was thinking it would be pretty easy to generate and publish.

    The idea is to come at the information from a different direction.  The existing version information works great if you already know about, for example, PrintPort.  But what if you're an experienced .NET 2.0 developer (or choose any "older" version).  In that case you've "probably" (hopefully?) been paying some attention to what Microsoft has been introducing in newer versions of .NET.  However that information is always on the "grand scale".  For example, "We've introduced LINQ -- It's GREAT!!".

    So as an experienced .NET 2.0 developer I realize that LINQ (just one example) now exists in newer .NET versions and I have a pretty good idea of the LINQ concept.  However, maybe I don't need LINQ.  There are a world of utility developers out there who don't really need LINQ.  So by not using LINQ, staying with 2.0, their utilities work on older version of Windows -- which might be a requirement or highly desirable given their customer base.

    What Microsoft doesn't do is make a big announcement about all the mundane, but often very useful, other things they've added to .NET.  I'm not faulting them.  It would be promotional stupidity to clutter the communications with a bunch of chatter about mundate things.

    For example, 3.0 started to expose much more of the printing stack as .NET classes.  I can't think of a single grand announcement about this.  If you check all the blogs, nobody felt it was "cool" enough to mention.  It was over-shadowed by all the "cool" improvements.

    Let's take even the "cool features".  Those tend to be entire ecosystems of new classes that get introduced.  In many cases, developers might not really need the highly touted cool new feature, but some of the classes introduced to support that new feature might prove useful.

    The idea of the version reference table is for developers to quickly see all the classes (and possibly other changes) that become available to them if they move from .NET version X to .NET version Y.  The list would be comprehensive, so that developers would find classes that were introduced in support of, as an example, LINQ, but which the developer might find useful without regard for LINQ itself.  Or in my case, I'd discover that an entire collection of printing stack classes was introduced that I knew nothing about -- even though I was paying attention to the "great new features" information coming out of Microsoft for each version.

    Experienced developers don't even really need much explanation within the table itself.  For example, the table doesn't need to tell me what "PrintPort" is.  It just needs to list it.  Experienced developers can make pretty accurate guesses about what a class is from its name, and they can click on the hyperlink and get confirmation from the main reference page for the class.

    As for listing enhancements... I'm a strong believer in return on investment.  I think there is a high return with minimal investment if the table is auto-generated using reflection and it requires no real human manipulation or management.

    A bare mimimum would be a table that simply listed when each class was introduced to the framework.  The next higher effort would be an indication of when new methods/properties were introduced to a class.  Getting fancier, auto-generating pages for each class that had additions to show those additions would be great.  Then the indicator on the main table would be a hyperlink to the table for that class.  Or perhaps the bare minimum is what's done for now, and building upon it is something for consideration later.

    At some point there is decreasing return on investment.  So I think the decision is really made based on how hard or time consuming it is to do any new level of information.  The minimal would be just a list of when classes were introduced, and perhaps just an indicator of when something new was added to a class.  Even the indicator might not prove all that useful if reflect shows that the majority of classes kept having additions.  At that point it's just a comment about "assume each class has been improved since chances are they have".
    -- kburgoyne
    Sunday, February 14, 2010 10:00 PM
  • Thanks for the suggestion kburgoyne,

    I've forwarded the thread to the Framework BCL documentation manager for review.

    You can also directly request new features by creating a Connect bug at https://connect.microsoft.com/VisualStudio/content/content.aspx?ContentID=14631

    -Steve
    Monday, February 22, 2010 8:18 PM
  • Hello kburgoyne,

    Steve has forwarded me your request.
    I agree with Karen that we already provide information about when each class was introduced on MSDN with the Version Information section for each API.
    Also, and I hope that's what you're looking for, we started a pilot project after we shipped .NET 3.5 SP1 called .NET Framework Version and Assembly Information. There you can find the first reports we created that list the API Differences from 3.5 to 3.5 SP1. You can choose Summary, by Namespace or by Assembly.
    We're planning to move this project to a more visible location and have the API Differences reports done from 3.5 SP1 to 4 when we ship .NET 4. Over time, we plan to include the reports for earlier releases as well.

    Regards,

    Maira Wenzel
    CLR UE Documentation Manager
    Monday, February 22, 2010 8:49 PM
  • Hi Maira,

    Excellent!  The "API Differences" pages are essentially what I was suggesting.  I assume they're under "Articles" because that was an easy place to stick them for the time being.  My recommendation would be eventually moving them under "what's new" (or "what's changed") sections for each of the .NET versions.

    I assume from the minimal formatting that the "API Differences" reference pages are generated by code.  If that's the case, I strongly recommend not waiting on .NET 4.  If the pages consisted of a lot of human work that would need to be kept updated as .NET 4 evolves, then I can see how the ROI would lean heavily toward waiting for more stability.  However if the pages can be auto-generated, now is the time that a large block of experienced developers are trying to get familiar with what's changed.

    Regarding the .NET documentation, this exercise has lead me to understanding at least one source of confusion about where a developer should go look for information.  I don't think it's really clear what the difference is between the following two branches, and why a developer would go to one branch or the other for information.

    .NET Framework Programming in Visual Studio
    http://msdn.microsoft.com/en-us/library/k1s94fta.aspx
    .NET Development
    http://msdn.microsoft.com/en-us/library/ff361664(VS.100).aspx

    It can be easy to get plopped into one or the other of the branches as the result of a search or other cross-reference, and not even realize there is another branch someplace else.

    I can guess that maybe the "in Visual Studio" branch is trying to be orientated toward what is bundled with a given Visual Studio version.  That's a good concept, but I'm under the (mis?) impression that it creates two bins that tend to catch different pieces of documentation that might be better organized into one area.  The "in Visual Studio" section might stop at a single overview page that contains primarily references to the one common .NET documentation branch.

    This also caused me to stumble upon the "Quick Technology Finder" page.  That's really excellent.  I didn't realize that had slipped into documentation.  Is there a "what's new in the MSDN documentation" alert that I didn't know to subscribe to?  If not, maybe it would be a great addition for us "old timers" who get pretty familiar with our existing ways and don't realize there is something new.  And if there is such an alert, maybe there needs to be an alert about changes in alerts. :-)

    The documentation team does great work!  Keeping up with how fast the MS developers are cranking out new stuff must be a challenge in itself.  On behalf of the development community, thanks for your efforts!

    -- Keith Burgoyne


    -- kburgoyne
    Monday, February 22, 2010 11:48 PM