Internal namespaces

One of the primary considerations when building a software platform on which other developers base their work is maintaining backward compatibility. As the platform grows more complex, this can become the major restraining factor when sustaining a high development pace.

Using strict semantic versioning, it becomes obvious that no API changes can be made, no matter how small the change or how obscure the class is, unless a major version is released. And while releasing a major version might not be as big a deal as it used to be, it does add additional work, not just internally, but also for maintainers of third-party modules trying to keep their modules up-to-date.

internal, <internal /> or .Internal?

The typical approach to this problem is to keep your public classes to a minimum and only expose classes that are useful to interact with for external developers. The API is currently limited primarily by keeping classes or methods internal.

One way of doing that is by adding the internal keyword to a class, but this is not the preferred way by users. Another option is to use the API documentation and explicitly call out the classes and methods that are considered internal. However, this has the drawback that it can sometimes be hard to track which APIs are public or not if they are spread out.

A third way, sometimes referred to as "pubternal" or "internal namespaces," consists of using a specific namespace pattern to indicate that you are now dealing with classes not part of the public API. Previously, Optimizely used the first two options, but since 2016, Optimizely has used the internal namespaces option.

This means that any class in a namespace named Internal is not considered a part of Optimizely-supported public API. Such classes can still be used, but the semantic versioning promise does not cover them and can change between minor releases without prior warning. Optimizely Support does not cover any problems that arise from using such classes.

It does, however, mean that Optimizely can expose more classes as public in the assemblies, making them easier to use if you need to or for non-production scenarios such as unit testing.

📘

Note

This does not imply that everything outside these namespaces is a part of the public API as there are still classes and methods that are explicitly documented as being for “internal use” but these are kept to a minimal whenever possible.

🚧

When you upgrade to Optimizely Content Management System (CMS 10 and higher)

In the first major release after Optimizely started using internal namespaces, CMS 10, a lot of classes where moved from their previous location to Internal namespaces. This included any classes not considered important for typical use cases or implementations of public abstractions. So when you upgrade a pre-version 10 solution, be careful and make sure that you do not accidentally add any Internal namespaces to your using statements as this may cause you problems in the future.