Get e-mail notification on new posts.

Developer network

Powered by

11 October 2011

Go to comments (2) Leave a comment

The API in Dynamicweb 8 is upgraded and modernized quite a bit compared to that of Dynamicweb 6 and Dynamicweb 7. In this post I’ll explain what we have done and how it will affect the release and the custom modules based on Dynamicweb 7 API.

Background

Since Dynamicweb was migrated from ASP to .NET back in 2005 a lot of features, modules and core elements have made its way into Dynamicweb API. In this process a lot of the new things were added to the API structure without a clear rule of where it should be placed in the namespace structure. This has left the API of Dynamicweb messed up. So when you access Dynamicweb.* in Visual Studio, intellisense goes crazy. Also the API exposes a lot of types and members that are used internally by the core and should not be exposed. This also making the API harder to overlook.

Intellisense going "crazy"

What are we doing

• Refactoring the API “facade” – this means that we reorder the namespace structure by moving types to the “right” place in the namespace structure, rename namespaces, types and members, updating naming and casing of parameters and members. On example is merging Dynamicweb.Template and Dynamicweb.Templatev2.Template into Dynamicweb.Rendering namespace.
• Making types and members that Dynamicweb uses internally and do not have much meaning for you as a 3rd party developer, internal.
• Deleting deprecated and unused code – code that is no longer in use. Example is Dynamicweb.Core
• Moving deprecated modules from Dynamicweb.dll to Dynamicweb.Compatibility.dll – so solutions can be installed without that code. Example is Dynamicweb.Weblog and Dynamicweb.Employee.
• Moving still supported modules from Dynamicweb.dll to Dynamicweb.Modules.dll. Example is Dynamicweb.Newsv2 moving to Dynamicweb.Modules.News namespace in Dynamicweb.Modules.dll
• Refactor utility classes. Example is Dynamicweb.Database where members like getDatareader and getConn are getting new names, overloads, documentation and samples (CreateDataread and CreateConnection). Also a utility class like Dynamicweb.Base is refactored and members moved to various places in the class/namespace structure. NOTE: We leave the old Base.* and Database.* members in the API so they can still be called and your code will still work. But we hide and deprecates them, giving compiler warnings.
• Change method signatures to follow correct casing - Method(parameterName). This does not have any impact on VB solutions – simply rebuild (or press CTRL + K +D). In C# solutions references to methods that changes casing will need to be fixed – calling Typename.Method instead of Typename.method. It is mostly parameter names that have changed – giving only a few code corrections.
• We do NOT rewrite a lot of code inside the types and members – so things are still working as they used to.

The goal

The goal is making the API better….!

• More intuitive API – typing Dynamicweb.* in Visual Studio should expose a type and namespace structure that is not overwhelming and makes some kind of sense.
• All public types and members should be documented with examples.
• Get rid of deprecated code – less to maintain.
• Make you faster developing modules and add-ons on Dynamicweb.

The result

When doing extensibility add-ons and custom modules on Dynamicweb 8 API and typing Dynamicweb.* in Visual Studio, you should see a way more DEVELOPERLICIOUS set of intellisense options.
Also the code base has decreased by 40% - this means fewer things that can break.


API and intellisense cleaned up.

The issues – and your challenges when upgrading

Of course all of this does not come for free. Until now solutions built on the Dynamicweb API back in 2005 is still working on the latest Dynamicweb 7 Service Release.
It will not work on the Dynamicweb 8 API…
This is what you should expect

• Change target framework to .NET 4
• In your code change import/using statements to the new namespaces. Today you write Templatev2.Template and you need to change to Rendering.Template – the rest of the code will still work.
• If you have code that uses i.e. Dynamicweb.Base.ChkString() it will still work – will give a compile warning, but no errors.
• The most commonly used parts of the API is still where it used to be – maybe hidden from intellisense and with compile warnings

One answer…

I’ve written that things will be “hidden” from intellisense, and give compile warnings – what does that mean?
A class like Dynamicweb.Base is something we want to remove from our API. We also acknowledge that there are thousands and thousands of calls to this class, and removing it would mean a lot of hours of you changing code.

That is boring – so here’s what we’ve done:

• We mark types and members with Browsable and EditorBrowsable attributes – to hide it when you type Dynamicweb.* - it is still there, but it will not show up in intellisense.
• We mark types and members that are deprecated with Obsolete attribute – most giving a compile warning, but some also a compile error. So you do not have to change it – but you should eventually.
• The deprecated member signature is left hidden in the API, but forwards its call to the new type and member handling it. i.e. Dynamicweb.Base.Request is forwarded internally to Dynamicweb.Input.Request.

How to leave members without congesting the API and intellisense.

Hope this gives an idea of what we are doing and why.

Please leave any comments, ideas and feedback - we can still incorporate things in the final release! THANKS.

Follow @nicped

Tweet