Usage

A zone is declared by a type implementing the empty IZone marker interface, and decorated with the [ZoneDefinition] attribute. The type can be a class or an interface, with no significance attached to the choice, although it has implications on inheritance. The simplest definition declares a zone with no dependencies:

[ZoneDefinition]
public interface ISimpleZone : IZone
{
}

Zone definitions are hierarchical, and can specify dependencies on other zones that are required in order for that zone to work. For example, the IPsiLanguageZone requires the PsiFeaturesImplZone which in turn requires the ITextControlsZone, IProjectModelZone and IDocumentModelZone. Any component that requires the IPsiLanguageZone implicitly also requires all of its dependencies. All zone definitions in this dependency hierarchy must be active for the component to be added to the Component Model.

The above example declares a zone with no dependencies - all components that belong to this zone can be instantiated without requiring any other zone to be active.

Dependencies can be defined either by inheritance or by implementing the IRequire<TZone> interface. The two methods are essentially the same, except inheritance also implies that depending zones are automatically activated. This is discussed in more detail in the Activation section. Generally speaking, unless there is an "is-a" relationship between zones (e.g. ILanguageCSharpZone is-a IPsiLanguageZone) dependencies should be implemented with the IRequire<TZone> marker interface. The two approaches can be mixed, as appropriate.

If a zone definition is expected to be inherited, it makes sense to implement it as an interface. In this way, the inheriting zone definition has the ability to inherit from multiple zones. If the base zone definition is a class, the inheriting zone definition can only inherit a single zone.

[ZoneDefinition]
public interface IMyZone : IZone, IRequire<NavigationZone>
{
}

This example states that IMyZone has a dependency on NavigationZone (and transitively, on anything that NavigationZone depends on, such as the PSI, results lists and options dialogs).

A zone definition has to be activated before it can be used. Typically, the owning product will be responsible for activating all of the zones in the product. For example, the ReSharperZonesActivator activates all zones used by ReSharper. When creating an extension that just consumes zones, activation is not needed, as the consumed zones will already be activated (or not, in which case the extension should not, and will not be loaded). However, if the extension creates zone definitions, it must activate them. This can be done either with explicitly with an activator class, or via the ZoneFlags.AutoEnable parameter to the ZoneDefinitionAttribute constructor. More details, including the differences between the approaches, can be found in the Activation guide.

Zone markers are used to declare that a component belongs to one or more zones. This means that the component can only be instantiated if all of those zones (and transitively, all dependent zones) are active in the product.

A zone marker is a class that has been decorated with the [ZoneMarker] attribute, and must be named ZoneMarker, or have a name that ends _ZoneMarker. All dependencies are listed either by implementing the IRequire<TZone> interface, or by passing the zone definitions to the ZoneMarkerAttribute constructor. There is no difference in the approach.

namespace Foo.Bar
{
  [ZoneMarker]
  public class ZoneMarker : IRequire<IMyZone>
  {
  }

  // or...
  // [ZoneMarker(typeof(IMyZone))]
  // public class ZoneMarker
  // {
  // }
}

This example declares that the Foo.Bar namespace belongs to the IMyZone zone. All components in the Foo.Bar namespace and below (e.g. both Foo.Bar.ThisComponent and Foo.Bar.Baz.Quux.ThatComponent) require the IMyZone zone, and all of its dependencies to be active, or they do not get added to the Component Model.

Multiple dependencies can be applied to the zone marker, meaning the components in the zone require multiple zones for their implementation. For example, a JavaScript unit test runner will require both the IUnitTestingZone and the ILanguageJavaScriptZone.

namespace Foo.Bar.JavaScriptTestRunner
{
  [ZoneMarker]
  public class ZoneMarker : IRequire<IUnitTestingZone>, IRequire<ILanguageJavaScriptZone>
  {
  }
}

Creating a zone marker with multiple dependencies can be considered an "anonymous" or "implicit" zone, made up of the listed dependencies, rather than explicitly defined with a zone definition class. Typically, this should only be used when the components that make up the zone are only to be used for end user facing features. There is no need for an explicit zone definition, because nobody needs to depend on these components and therefore include the zone in an IRequire<TZone>.

However, if the components are expected to be used by another zone (that is, the feature is an internal, code facing feature) then a zone definition should be created that encapsulates the dependencies. The zone marker should then only require this single, new zone definition, and no others. This gives depending code a zone definition it can require. Failure to do this means error prone repetition of zone dependencies in the dependent zones.

Put another way, consider the dependencies of a zone to be an implementation detail. Do not require depending code to know your dependencies in order to consume your components - provide a zone definition.

namespace Foo.Bar
{
  [ZoneMarker]
  public class ZoneMarker
  {
  }
}

// The namespace of the zone definition is irrelevant
[ZoneDefinition]
public interface IMyZone : IDependentZone
{
}

namespace Foo.Bar
{
  [ZoneMarker]
  public class ZoneMarker : IZone, IRequire<IMyZone>
  {
  }
}

namespace Foo.Bar.Baz
{
  [ShellComponent]
  public class MyComponent
  {
  }
}