With the release of Telligent Community 10.0 just around the corner we wanted to share some details about one of the larger developments efforts in this release: Assembly Restructuring.
In Telligent Community 10.0 we have re-organized the platform code so that there is a clear separation of the platform (sometimes referred to as "core") code from the applications themselves. With this change the platform code and infrastructure do not depend on any specific application and application changes will not have any impact on the platform. The applications within Community (ideation, forums, blogs, etc) will interact with the platform the same way as any custom application or custom code would - through supported APIs.
With the separation of application and platform code, applications will own their own APIs. There is no longer a single API library to reference, instead you will reference the application and/or platform specific libraries and only the ones you need.
In 10.0 for any new development you should take advantage of this immediately. If you had previous customizations you will not be required to change your references until the next major release. This is possible because of a process known as Type Forwarding. This is a feature of .NET that allows the runtime to redirect requests for APIs in the old locations to its new ones without the need to change any code. If however at anytime you need to recompile that custom code for any reason you will be forced to update the references in order for the code to compile correctly and update your framework usage to .NET 4.6.2. There will be more detail on how to make these updates later in the article. Remember that all custom code will be required to update its references and framework version before the next major version.
PublicApi Class Deprecated
Another change is how we recommend you to interact with the in-process APIs. If you have worked with the platform for a while odds are you have interacted with the global, static Telligent.Evolution.Extensibility.Api.Version1.PublicApi class. While this class was easy to find and easy to use, it was not extensible and it created unnecessary dependencies with all aspects of the product. In version 8.5, we introduced a better solution that allows APIs to be registered with the platform via a new plugin type - Telligent.Evolution.Extensibility.Api.IApiDefinition. In turn you access all registered APIs via Telligent.Evolution.Extensibility.Apis.Get<T>. This solution creates an abstraction layer for APIs that allow the management of an API to be a platform task, decoupling it from any specific application. This approach is still easy to use, provides the necessary separation of concerns and opens up the platform for developers to add their own APIs using a consistent pattern. In 10.0, PublicApi still exists for backward compatibility but it has been deprecated and we are recommending you update your code to use Apis.Get<T>. The PublicApi static class will be completely removed in the next major version.
How do I update my code?
If you choose to update your code before the next major release, it is a pretty straightforward process. You are not required to do this for 10.0 unless you choose to Or you have to recompile your code. You will need to make these changes in the next major version.
- Change to .NET 4.6.2. You can do this by selecting the property pages of your project in Visual Studio(right click menu of the project) and then changing the target framework on the application tab.
- Update Your Project references
- If you have a reference to Telligent.Evolution.Components.dll, Telligent.Evolution.Api.dll, Telligent.Evolution.Core.dll or Telligent.Evolution.REST.dll replace it with Telligent.Evolution.Platform.dll.
- If you use application specific APIs, reference the application specific references:
- Blogs -> Telligent.Evolution.Blogs.dll
- Forums -> Telligent.Evolution.Forums.dll
- Wikis -> Telligent.Evolution.Wikis.dll
- Galleries -> Telligent.Evolution.MediaGalleries.dll
- Calendar -> Telligent.Evolution.Calendar.dll
- Ideas -> Telligent.Evolution.Ideation.dll.
- Users, Groups, Custom Plugins and anything not listed above -> Telligent.Evolution.Platform.dll.
- Replace Telligent.Evolution.Extensibility.Api.Version1.PublicApi with Apis.Get<T>(Optional in 10.X)
- API reference documentation provides examples of using Apis.Get<>(). You can always use this documentation to locate the appropriate interface for a specific API.
- Interacting with the APIs is no different. For example, if you previously called PublicApi.Blogs.List(...) it would be Apis.Get<IBlogs>().List(...).
- Common API usages:
- PublicApi.Blogs -> Api.Get<IBlogs>()
- PublicApi.BlogPosts -> Api.Get<IBlogPosts>()
- PublicApi.Forums -> Api.Get<IForums>()
- PublicApi.ForumThreads -> Api.Get<IForumThreads>()
- PublicApi.ForumReplies >Api.Get<IForumReplies>()
- PublicApi.Groups -> Api.Get<IGroups>()
- PublicApi.Users -> Api>Get<IUsers>()
- PublicApi.Tags -> Api.Get<ITags>()
Frequently Asked questions
Q. I wrote a custom widget for my community in widget studio using Community APIs, will it continue to work?
A. Yes. All of the community APIs used through widget studio continue to work as they did.
Q. Telligent Currently hosts my community and the only changes I have made are some changes to existing widgets and to my theme, will my changes still work?
A. Yes. Functionality provided out of the box and manipulated through the UI or administration has not changed.
Q. I am a third party application developer and I integrated with the community using REST APIs (or the Community REST SDK), will my REST calls still work?
A. Yes. REST API usage has not changed.
Q. If I wrote a custom plugin of any type will I need to re-compile and/or change my code?
A. No. If you just want to use your plugin as it was in your old version(re-deploy the dll) and it used only supported APIs then you can simply redeploy the assembly from your plugin to 10.0. If you need to make changes or recompile at anytime however, you will need to at minimum update to .NET 4.6.2 and update the references as described above.
Q. With all the API moves are supported APIs still in the Telligent.Evolution.Extensibility namespaces?
A. Yes. We did not change the namespaces when we moved Apis and that namespace still remains the way to identify supported Apis from code. If you are using code not in this namespace or documented as an API, you should consider this a good time to change those over to supported Apis. Unsupported APIs can be removed or changed at any time without notice.
Q. Telligent told me they would not break supported APIs. Is Telligent still committed to upgrade safety and extensibility?
A. Yes, absolutely. This is the reason we introduced the type forwarding concept, to maintain backwards compatibility for existing code through version 10. This way you are not forced to make changes and can plan accordingly for the next major version. If an API was deprecated in an earlier version and removed in 10 and you are still using it, you will need to update it, which would include updating .NET and references.
Q. I have Telligent Community and Telligent Professional Services did a lot of work on my community, do I need to contact them before I upgrade to version 10?
A. No. If you are not planning on any changes that result in a recompile you should be fine. It may not hurt however to at least ask, we are more than happy to answer any questions.
Q. I wanted to add enhancements to my customization code after we upgrade, will I need to update my references? What if I need to fix a bug?
A. Yes. Type forwarding is only a feature of the .NET runtime (CLR), which means it can only occur when the code is executing. It does not occur during compilation so in order for your code to build successfully, you will need to update your references and .NET version at minimum.