Difference between revisions of "HowTo:Provide system definitions with a custom plugin"
(→See also) |
(→See also) |
||
| (One intermediate revision by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | This tutorial explains how to provide any kind of preconfigured {{UBIK}} | + | This tutorial explains how to provide any kind of preconfigured {{UBIK}} system definitions using a custom plugin (or more specific: module). |
== General concept == | == General concept == | ||
| Line 19: | Line 19: | ||
= Big Picture = | = Big Picture = | ||
| − | The | + | The Module implementation hosts a System Definition Provider, which in turn gives access to a set of versioned System Definitions. The latter can contain any kind of {{UBIK}} data like MetaClasses, MetaProperties, instances of any type and scripts to execute when the package is installed or initialized. |
[[File:Systemdefinitions2.drawio.png]] | [[File:Systemdefinitions2.drawio.png]] | ||
| Line 1,058: | Line 1,058: | ||
* [[Injection_Management]] | * [[Injection_Management]] | ||
* [[Plugins]] | * [[Plugins]] | ||
| + | * [[UBIK_Plugin_Design]] | ||
[[Category:How-To|Provide system definitions with a custom plugin]] | [[Category:How-To|Provide system definitions with a custom plugin]] | ||
| − | |||
[[Category:Injecting|Provide system definitions with a custom plugin]] | [[Category:Injecting|Provide system definitions with a custom plugin]] | ||
| + | [[Category:Module|Provide system definitions with a custom plugin]] | ||
[[Category:Plugin|Provide system definitions with a custom plugin]] | [[Category:Plugin|Provide system definitions with a custom plugin]] | ||
Latest revision as of 07:46, 6 October 2025
This tutorial explains how to provide any kind of preconfigured UBIK® system definitions using a custom plugin (or more specific: module).
General concept
When rolling out a UBIK® customizing into a (productive) environment, there is always the challenge regarding the transportation of the data model and basic data. The sustainable solution is to deliver versioned packages of system definitions in plugins, because that allows for easy deployment and upgrade, and for the direct application of state-of-the-art software development strategies for plugin development.
UBIK® plugins are detected when an Environment is initialized, and the user is prompted with a database upgrade if necessary. The technical maintenance of the database is automatic and allows for arbitrary adaptations. The plugin developer can decide whether to make meta definitions immutable (as system design objects in the System namespace) or further customizable by the user (as regular content). Custom scripts can be executed every time the Environment is connected or just during an upgrade.
Prerequisites
To understand the code, knowledge about the UBIK® ER-model and the plugin injection mechanism is required.
Instructions
[edit]
- Big Picture
- Create a new plugin
- Create a new SystemDefinitionProvider
- Create a new SystemDefinitions package
- Add a new basic MetaClass
- Add a new special MetaClass
- Add new arbitrary instances
- Provide a version upgrade
- Create a new MetaProxy
- Create a system classification
- Create a system SelectiveList
- Perform pre- or postprocessing scripts
- Create a custom InterfaceAdmin
Big Picture
The Module implementation hosts a System Definition Provider, which in turn gives access to a set of versioned System Definitions. The latter can contain any kind of UBIK® data like MetaClasses, MetaProperties, instances of any type and scripts to execute when the package is installed or initialized.
Create a new plugin
The plugin class is the central access point for your definitions. It must implement the IUbikModule interface for the system definitions to be applied.
Plugin template code
namespace UBIK.MyPlugin
{
[Export(typeof(UBIK.Injection.IUbikPlugin))]
[ExportMetadata("ID", "e9395ebd-4e41-40a3-9ac6-01bce6fb7e68")]
[ExportMetadata("Type", typeof(MyPlugin))]
[ExportMetadata("Name", "MyPlugin")]
[ExportMetadata("Description", "My custom plugin")]
[ExportMetadata("Version", 1)]
[ExportMetadata("Company", "Augmensys GmbH")]
[ExportMetadata("MinimumKernelVersion", "4.0.0.0")]
public class MyPlugin: IUbikModule
{
public static Guid ID
{
get
{
return Guid.Parse("e9395ebd-4e41-40a3-9ac6-01bce6fb7e68");
}
}
public UBIKEnvironment Environment { get; private set; }
public ISystemDefinitionProvider SystemDefinitionsProvider
{
get
{
return MySystemDefinitionProvider.Instance;
}
}
public virtual void Initialize(UBIKEnvironment environment)
{
this.Environment = environment;
}
public virtual void Terminate()
{
this.Environment = null;
}
public virtual bool Initialized()
{
return this.Environment != null;
}
public List<ModuleInfo> DependencyModules
{
get;
} = new List<ModuleInfo>();
}
}
{
[Export(typeof(UBIK.Injection.IUbikPlugin))]
[ExportMetadata("ID", "e9395ebd-4e41-40a3-9ac6-01bce6fb7e68")]
[ExportMetadata("Type", typeof(MyPlugin))]
[ExportMetadata("Name", "MyPlugin")]
[ExportMetadata("Description", "My custom plugin")]
[ExportMetadata("Version", 1)]
[ExportMetadata("Company", "Augmensys GmbH")]
[ExportMetadata("MinimumKernelVersion", "4.0.0.0")]
public class MyPlugin: IUbikModule
{
public static Guid ID
{
get
{
return Guid.Parse("e9395ebd-4e41-40a3-9ac6-01bce6fb7e68");
}
}
public UBIKEnvironment Environment { get; private set; }
public ISystemDefinitionProvider SystemDefinitionsProvider
{
get
{
return MySystemDefinitionProvider.Instance;
}
}
public virtual void Initialize(UBIKEnvironment environment)
{
this.Environment = environment;
}
public virtual void Terminate()
{
this.Environment = null;
}
public virtual bool Initialized()
{
return this.Environment != null;
}
public List<ModuleInfo> DependencyModules
{
get;
} = new List<ModuleInfo>();
}
}
Create a new SystemDefinitionProvider
The SystemDefinitionProvider has a list of all supported system definitions packages. The base implementation uses the version information from the packages to handle the upgrading.
SystemDefinitionsProvider template code
namespace UBIK.MyPlugin
{
public class MySystemDefinitionProvider : SystemDefinitionProviderBase
{
public override Guid ModuleID => MyPlugin.ID;
private static MySystemDefinitionProvider instance = null;
public static MySystemDefinitionProvider Instance
{
get
{
return instance ?? (instance = new MySystemDefinitionProvider());
}
}
private MySystemDefinitionProvider() :
base(
new MySystemDefinitions_V100(),
new MySystemDefinitions_V110())
{ }
}
}
{
public class MySystemDefinitionProvider : SystemDefinitionProviderBase
{
public override Guid ModuleID => MyPlugin.ID;
private static MySystemDefinitionProvider instance = null;
public static MySystemDefinitionProvider Instance
{
get
{
return instance ?? (instance = new MySystemDefinitionProvider());
}
}
private MySystemDefinitionProvider() :
base(
new MySystemDefinitions_V100(),
new MySystemDefinitions_V110())
{ }
}
}
Create a new SystemDefinitions package
The SystemDefinitions contain any data you may want to deliver with your plugin.
SystemDefinitions package template code
namespace UBIK.MyPlugin
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
#region Constants
public static readonly Version VERSION = new Version(1, 0, 0, 0);
#endregion Constants
#region Version
public override Version Version
{
get
{
return VERSION;
}
}
#endregion Version
#region System Classifications
public override UBIKClassList<MetaClass> DefineSystemClassifications(UBIKEnvironment environment)
{
return new UBIKClassList<MetaClass>();
}
#endregion System Classifications
#region System Meta Classes
public override UBIKClassList<MetaClass> DefineSystemMetaClasses(UBIKEnvironment environment)
{
UBIKClassList<MetaClass> metaClasses = new UBIKClassList<MetaClass>();
return metaClasses;
}
#endregion System Meta Classes
#region System Meta Properties
public override UBIKClassList<MetaProperty> DefineSystemMetaProperties(UBIKEnvironment environment)
{
UBIKClassList<MetaProperty> result = new UBIKClassList<MetaProperty>();
return result;
}
#endregion System Meta Properties
#region System Selective Lists
public override UBIKClassList<SelectiveList> DefineSystemSelectiveLists(UBIKEnvironment environment)
{
UBIKClassList<SelectiveList> result = new UBIKClassList<SelectiveList>();
return result;
}
#endregion System Selective Lists
#region Module Definition
public override void UpdateSystemContent(UBIKEnvironment environment)
{
UpdateModuleDefinition(environment);
}
protected void UpdateModuleDefinition(UBIKEnvironment environment)
{
MetaClass moduleMc = environment.GetSystemMetaClass(SystemObjects.MODULE);
BaseClass module = moduleMc.GetOrCreateInstance(MyPlugin.ID);
module.Name = "MyPlugin";
module.Namespace = "MyPlugin";
if (environment.LanguageManager.TryGetLanguageIndex("de", out int idxDe))
{
module.SetInternationalDescription(idxDe, "UBIK Plugin Vorlage. (C) Augmensys GmbH");
}
if (environment.LanguageManager.TryGetLanguageIndex("en", out int idxEn))
{
module.SetInternationalDescription(idxEn, "UBIK template plugin. (C) Augmensys GmbH");
}
module.Save();
}
#endregion Module Definition
}
}
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
#region Constants
public static readonly Version VERSION = new Version(1, 0, 0, 0);
#endregion Constants
#region Version
public override Version Version
{
get
{
return VERSION;
}
}
#endregion Version
#region System Classifications
public override UBIKClassList<MetaClass> DefineSystemClassifications(UBIKEnvironment environment)
{
return new UBIKClassList<MetaClass>();
}
#endregion System Classifications
#region System Meta Classes
public override UBIKClassList<MetaClass> DefineSystemMetaClasses(UBIKEnvironment environment)
{
UBIKClassList<MetaClass> metaClasses = new UBIKClassList<MetaClass>();
return metaClasses;
}
#endregion System Meta Classes
#region System Meta Properties
public override UBIKClassList<MetaProperty> DefineSystemMetaProperties(UBIKEnvironment environment)
{
UBIKClassList<MetaProperty> result = new UBIKClassList<MetaProperty>();
return result;
}
#endregion System Meta Properties
#region System Selective Lists
public override UBIKClassList<SelectiveList> DefineSystemSelectiveLists(UBIKEnvironment environment)
{
UBIKClassList<SelectiveList> result = new UBIKClassList<SelectiveList>();
return result;
}
#endregion System Selective Lists
#region Module Definition
public override void UpdateSystemContent(UBIKEnvironment environment)
{
UpdateModuleDefinition(environment);
}
protected void UpdateModuleDefinition(UBIKEnvironment environment)
{
MetaClass moduleMc = environment.GetSystemMetaClass(SystemObjects.MODULE);
BaseClass module = moduleMc.GetOrCreateInstance(MyPlugin.ID);
module.Name = "MyPlugin";
module.Namespace = "MyPlugin";
if (environment.LanguageManager.TryGetLanguageIndex("de", out int idxDe))
{
module.SetInternationalDescription(idxDe, "UBIK Plugin Vorlage. (C) Augmensys GmbH");
}
if (environment.LanguageManager.TryGetLanguageIndex("en", out int idxEn))
{
module.SetInternationalDescription(idxEn, "UBIK template plugin. (C) Augmensys GmbH");
}
module.Save();
}
#endregion Module Definition
}
}
Add a new basic MetaClass
Here's how you can add a new MetaClass (and MetaProperty) to be shipped with your plugin.
SystemDesignMetaClass template code
namespace UBIK.MyPlugin
{
public class MyBaseMetaClass : SystemDesignMetaClass
{
public static readonly Guid UID = Guid.Parse("30ed406b-a5f1-498b-ad34-2db1bd786b13");
private const string NAME = "MY_BASECLASS";
private const string NAMESPACE = "System.MyPlugin";
private const string DESCRIPTION = "My Baseclass";
public MyBaseMetaClass(UBIKEnvironment environment)
{
InitUidAndEnvironment(UID, environment);
InitStrings(NAME, NAMESPACE, DESCRIPTION);
SetModuleId(MyPlugin.ID);
DefineMetaProperties(new List<Guid>() {
MyMetaProperties.PROPERTY_UID_MYPROPERTY
});
}
public override MetaClass Inheritance
{
get
{
return this.Environment.GetSystemMetaClass(SystemObjects.NAMEDBASECLASS);
}
set
{
// do nothing
}
}
public override MetaClassTypes ClassType
{
get
{
return MetaClassTypes.Inherited;
}
set
{
// do nothing
}
}
}
}
{
public class MyBaseMetaClass : SystemDesignMetaClass
{
public static readonly Guid UID = Guid.Parse("30ed406b-a5f1-498b-ad34-2db1bd786b13");
private const string NAME = "MY_BASECLASS";
private const string NAMESPACE = "System.MyPlugin";
private const string DESCRIPTION = "My Baseclass";
public MyBaseMetaClass(UBIKEnvironment environment)
{
InitUidAndEnvironment(UID, environment);
InitStrings(NAME, NAMESPACE, DESCRIPTION);
SetModuleId(MyPlugin.ID);
DefineMetaProperties(new List<Guid>() {
MyMetaProperties.PROPERTY_UID_MYPROPERTY
});
}
public override MetaClass Inheritance
{
get
{
return this.Environment.GetSystemMetaClass(SystemObjects.NAMEDBASECLASS);
}
set
{
// do nothing
}
}
public override MetaClassTypes ClassType
{
get
{
return MetaClassTypes.Inherited;
}
set
{
// do nothing
}
}
}
}
SystemDesignMetaProperty template code
namespace UBIK.MyPlugin
{
public class MyMetaProperties
{
public const string NS_MY_PLUGIN = "System.MyPlugin";
public static readonly Guid PROPERTY_UID_MYPROPERTY = Guid.Parse("d90b50e0-17d9-40ac-b89d-18f4a01cd5cb");
public const string PROPERTY_NAME_MYPROPERTY = "LK_LOCATION";
public static UBIKClassList<MetaProperty> DefineSystemMetaProperties(UBIKEnvironment environment)
{
MetaProperty myProperty = SystemDesignMetaProperty.CreateStringSystemDesignMetaProperty
(environment, PROPERTY_NAME_MYPROPERTY, NS_MY_PLUGIN, PROPERTY_UID_MYPROPERTY, multiLang: false, orderID: 0, stringLen: 0);
myProperty.Description = "MyProperty";
UBIKClassList<MetaProperty> metaProperties = new UBIKClassList<MetaProperty>() {
myProperty
};
return metaProperties;
}
}
}
{
public class MyMetaProperties
{
public const string NS_MY_PLUGIN = "System.MyPlugin";
public static readonly Guid PROPERTY_UID_MYPROPERTY = Guid.Parse("d90b50e0-17d9-40ac-b89d-18f4a01cd5cb");
public const string PROPERTY_NAME_MYPROPERTY = "LK_LOCATION";
public static UBIKClassList<MetaProperty> DefineSystemMetaProperties(UBIKEnvironment environment)
{
MetaProperty myProperty = SystemDesignMetaProperty.CreateStringSystemDesignMetaProperty
(environment, PROPERTY_NAME_MYPROPERTY, NS_MY_PLUGIN, PROPERTY_UID_MYPROPERTY, multiLang: false, orderID: 0, stringLen: 0);
myProperty.Description = "MyProperty";
UBIKClassList<MetaProperty> metaProperties = new UBIKClassList<MetaProperty>() {
myProperty
};
return metaProperties;
}
}
}
SystemDefinitions adaptations
namespace UBIK.MyPlugin
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
// ...
#region System Meta Classes
public override UBIKClassList<MetaClass> DefineSystemMetaClasses(UBIKEnvironment environment)
{
UBIKClassList<MetaClass> metaClasses = new UBIKClassList<MetaClass>();
MyBaseMetaClass myBaseClass = new MyBaseMetaClass(environment);
metaClasses.Add(myBaseClass);
return metaClasses;
}
#endregion System Meta Classes
#region System Meta Properties
public override UBIKClassList<MetaProperty> DefineSystemMetaProperties(UBIKEnvironment environment)
{
UBIKClassList<MetaProperty> result = new UBIKClassList<MetaProperty>();
result.AddRangeUnique(MyMetaProperties.DefineSystemMetaProperties(environment));
return result;
}
#endregion System Meta Properties
// ...
}
}
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
// ...
#region System Meta Classes
public override UBIKClassList<MetaClass> DefineSystemMetaClasses(UBIKEnvironment environment)
{
UBIKClassList<MetaClass> metaClasses = new UBIKClassList<MetaClass>();
MyBaseMetaClass myBaseClass = new MyBaseMetaClass(environment);
metaClasses.Add(myBaseClass);
return metaClasses;
}
#endregion System Meta Classes
#region System Meta Properties
public override UBIKClassList<MetaProperty> DefineSystemMetaProperties(UBIKEnvironment environment)
{
UBIKClassList<MetaProperty> result = new UBIKClassList<MetaProperty>();
result.AddRangeUnique(MyMetaProperties.DefineSystemMetaProperties(environment));
return result;
}
#endregion System Meta Properties
// ...
}
}
Add a new special MetaClass
In some cases you need to defined something more elaborate, e.g., a MetaClass with custom code deriving from another MetaClass you defined.
SystemDesignMetaClass template code
namespace UBIK.MyPlugin
{
public class MySpecialMetaClass : SystemDesignMetaClass
{
public static readonly Guid UID = Guid.Parse("0925ad66-7199-4e70-871c-cdd799f8d8e7");
private const string NAME = "MY_SEPCIALCLASS";
private const string NAMESPACE = "System.MyPlugin";
private const string DESCRIPTION = "My special class";
private MyBaseMetaClass parent = null;
public MySpecialMetaClass(UBIKEnvironment environment, MyBaseMetaClass parent)
{
InitUidAndEnvironment(UID, environment);
InitStrings(NAME, NAMESPACE, DESCRIPTION);
SetModuleId(MyPlugin.ID);
this.parent = parent;
DefineMetaProperties(new List<Guid>() {
// ...
});
}
public override MetaClass Inheritance
{
get
{
return this.parent;
}
set
{
// do nothing
}
}
public override MetaClassTypes ClassType
{
get
{
return MetaClassTypes.DEFINED_IN_PLUGIN;
}
set
{
// do nothing
}
}
public override Type GetRuntimeType()
{
return typeof(MySpecialType);
}
public override Type GetSystemRuntimeType()
{
return typeof(MySpecialType);
}
}
}
{
public class MySpecialMetaClass : SystemDesignMetaClass
{
public static readonly Guid UID = Guid.Parse("0925ad66-7199-4e70-871c-cdd799f8d8e7");
private const string NAME = "MY_SEPCIALCLASS";
private const string NAMESPACE = "System.MyPlugin";
private const string DESCRIPTION = "My special class";
private MyBaseMetaClass parent = null;
public MySpecialMetaClass(UBIKEnvironment environment, MyBaseMetaClass parent)
{
InitUidAndEnvironment(UID, environment);
InitStrings(NAME, NAMESPACE, DESCRIPTION);
SetModuleId(MyPlugin.ID);
this.parent = parent;
DefineMetaProperties(new List<Guid>() {
// ...
});
}
public override MetaClass Inheritance
{
get
{
return this.parent;
}
set
{
// do nothing
}
}
public override MetaClassTypes ClassType
{
get
{
return MetaClassTypes.DEFINED_IN_PLUGIN;
}
set
{
// do nothing
}
}
public override Type GetRuntimeType()
{
return typeof(MySpecialType);
}
public override Type GetSystemRuntimeType()
{
return typeof(MySpecialType);
}
}
}
Special runtime type template code
namespace UBIK.MyPlugin
{
public class MySpecialType : ContentClass
{
// This implementation will be used to instantiate respective instances in UBIK during runtime.
// Here you can override anything that can be overridden in UBIK.Studio's code editor, and more.
// Additional code may be added, too.
}
}
{
public class MySpecialType : ContentClass
{
// This implementation will be used to instantiate respective instances in UBIK during runtime.
// Here you can override anything that can be overridden in UBIK.Studio's code editor, and more.
// Additional code may be added, too.
}
}
SystemDefinitions adaptations
namespace UBIK.MyPlugin
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
// ...
#region System Meta Classes
protected MyBaseMetaClass MyBaseMetaClass { get; set; }
protected MySpecialMetaClass MySpecialMetaClass { get; set; }
public override UBIKClassList<MetaClass> DefineSystemMetaClasses(UBIKEnvironment environment)
{
UBIKClassList<MetaClass> metaClasses = new UBIKClassList<MetaClass>();
MyBaseMetaClass = new MyBaseMetaClass(environment);
metaClasses.Add(MyBaseMetaClass);
MySpecialMetaClass = new MySpecialMetaClass(environment, MyBaseMetaClass);
metaClasses.Add(MySpecialMetaClass);
return metaClasses;
}
#endregion System Meta Classes
// ...
}
}
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
// ...
#region System Meta Classes
protected MyBaseMetaClass MyBaseMetaClass { get; set; }
protected MySpecialMetaClass MySpecialMetaClass { get; set; }
public override UBIKClassList<MetaClass> DefineSystemMetaClasses(UBIKEnvironment environment)
{
UBIKClassList<MetaClass> metaClasses = new UBIKClassList<MetaClass>();
MyBaseMetaClass = new MyBaseMetaClass(environment);
metaClasses.Add(MyBaseMetaClass);
MySpecialMetaClass = new MySpecialMetaClass(environment, MyBaseMetaClass);
metaClasses.Add(MySpecialMetaClass);
return metaClasses;
}
#endregion System Meta Classes
// ...
}
}
Add new arbitrary instances
In some cases you may want to deliver instances of an arbitrary type the user can change to their liking.
SystemDefinitions adaptations
namespace UBIK.MyPlugin
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
public static readonly Guid DEFAULT_INSTANCE_UID = Guid.Parse("a71c2c7e-a7b7-4462-b1c8-61ea9cba0dcd");
// ...
#region System Content
public override void UpdateSystemContent(UBIKEnvironment environment)
{
MySpecialType defaultInstance = MySpecialMetaClass.GetOrCreateInstance(DEFAULT_INSTANCE_UID) as MySpecialType;
if (defaultInstance.IsNewInstance)
{
defaultInstance.Namespace = "MyPlugin.Default";
defaultInstance.Name = "MySpecialInstance";
defaultInstance.Description = "Default instance";
defaultInstance.Save();
}
}
#endregion System Content
// ...
}
}
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
public static readonly Guid DEFAULT_INSTANCE_UID = Guid.Parse("a71c2c7e-a7b7-4462-b1c8-61ea9cba0dcd");
// ...
#region System Content
public override void UpdateSystemContent(UBIKEnvironment environment)
{
MySpecialType defaultInstance = MySpecialMetaClass.GetOrCreateInstance(DEFAULT_INSTANCE_UID) as MySpecialType;
if (defaultInstance.IsNewInstance)
{
defaultInstance.Namespace = "MyPlugin.Default";
defaultInstance.Name = "MySpecialInstance";
defaultInstance.Description = "Default instance";
defaultInstance.Save();
}
}
#endregion System Content
// ...
}
}
Provide a version upgrade
If you released system definitions previously, which are already used productively, how do you deliver changes? The solution is to not change the older version, but create a newer version instead. We always want to stay downward compatible.
SystemDefinitions adaptations
namespace UBIK.MyPlugin
{
public class MySystemDefinitions_V110 : MySystemDefinitions_V100
{
#region Constants
public static readonly Version VERSION = new Version(1, 1, 0, 0);
#endregion Constants
#region Version
public override Version Version
{
get
{
return VERSION;
}
}
#endregion Version
// ...
#region System Meta Classes
// Refactor MySystemDefinitions_V100 so the "MyBaseMetaClass" is defined in a separate method, so we can override it!
public override MyBaseMetaClass DefineMyBaseMetaClass(UBIKEnvironment environment)
{
MyBaseMetaClass mc = new MyBaseMetaClass_V110(environment);
// MyBaseMetaClass_V110 should derive from the original MyBaseMetaClass, adapting it to the new version
return mc;
}
#endregion System Meta Classes
// ...
}
}
{
public class MySystemDefinitions_V110 : MySystemDefinitions_V100
{
#region Constants
public static readonly Version VERSION = new Version(1, 1, 0, 0);
#endregion Constants
#region Version
public override Version Version
{
get
{
return VERSION;
}
}
#endregion Version
// ...
#region System Meta Classes
// Refactor MySystemDefinitions_V100 so the "MyBaseMetaClass" is defined in a separate method, so we can override it!
public override MyBaseMetaClass DefineMyBaseMetaClass(UBIKEnvironment environment)
{
MyBaseMetaClass mc = new MyBaseMetaClass_V110(environment);
// MyBaseMetaClass_V110 should derive from the original MyBaseMetaClass, adapting it to the new version
return mc;
}
#endregion System Meta Classes
// ...
}
}
Create a new MetaProxy
MetaProxies are managed very similarly to MetaClasses, but the MetaProxyProperties are slightly more complex because they require additional information like the UIDs for the import and export versions of itself, the target property in UBIK®, etc.
SystemDesignMetaProxy template code
namespace UBIK.MyPlugin
{
public class MyProxyMetaClass : SystemDesignMetaProxy
{
public static Guid UID = GuidUtility.MY_PROXY;
private const string NAME = "MYPROXY";
private const string NAMESPACE = "System.MyPlugin";
private const string DESCRIPTION = "My meta proxy";
public MyProxyMetaClass(UBIKEnvironment environment)
{
InitUidAndEnvironment(UID, environment);
InitStrings(NAME, NAMESPACE, DESCRIPTION);
SetModuleId(MyPlugin.ID);
List<Guid> metaProperties = new List<Guid>();
// regular meta properties
DefineMetaProperties(metaProperties);
List<MetaProxyPropertyInfo> metaProxyPropertyInfos = new List<MetaProxyPropertyInfo>();
metaProxyPropertyInfos.Add(new MetaProxyPropertyInfo(environment, MyProxyMetaProperties.PROXY_PROPERTY_UID_MYPROPERTY, true, -1, ProxyUpdateModes.BiDirectional, MyMetaProperties.PROPERTY_UID_MYPROPERTY, "My property"));
DefineMetaProxyProperties(metaProxyPropertyInfos);
}
public override MetaClass MetaClass
{
get
{
return this.Environment.GetSystemMetaClass(SystemObjects.METAPROXY);
}
}
public override MetaClass Inheritance
{
get
{
return this.Environment.GetSystemMetaClass(SystemObjects.PROXY_ROOT);
}
set
{
// do nothing
}
}
public override MetaClassTypes ClassType
{
get
{
return MetaClassTypes.Proxy;
}
set
{
// do nothing
}
}
}
}
{
public class MyProxyMetaClass : SystemDesignMetaProxy
{
public static Guid UID = GuidUtility.MY_PROXY;
private const string NAME = "MYPROXY";
private const string NAMESPACE = "System.MyPlugin";
private const string DESCRIPTION = "My meta proxy";
public MyProxyMetaClass(UBIKEnvironment environment)
{
InitUidAndEnvironment(UID, environment);
InitStrings(NAME, NAMESPACE, DESCRIPTION);
SetModuleId(MyPlugin.ID);
List<Guid> metaProperties = new List<Guid>();
// regular meta properties
DefineMetaProperties(metaProperties);
List<MetaProxyPropertyInfo> metaProxyPropertyInfos = new List<MetaProxyPropertyInfo>();
metaProxyPropertyInfos.Add(new MetaProxyPropertyInfo(environment, MyProxyMetaProperties.PROXY_PROPERTY_UID_MYPROPERTY, true, -1, ProxyUpdateModes.BiDirectional, MyMetaProperties.PROPERTY_UID_MYPROPERTY, "My property"));
DefineMetaProxyProperties(metaProxyPropertyInfos);
}
public override MetaClass MetaClass
{
get
{
return this.Environment.GetSystemMetaClass(SystemObjects.METAPROXY);
}
}
public override MetaClass Inheritance
{
get
{
return this.Environment.GetSystemMetaClass(SystemObjects.PROXY_ROOT);
}
set
{
// do nothing
}
}
public override MetaClassTypes ClassType
{
get
{
return MetaClassTypes.Proxy;
}
set
{
// do nothing
}
}
}
}
SystemDesignMetaProxyProperty template code
namespace UBIK.MyPlugin
{
public class MyMetaProxyProperties
{
public const string NS_MY_PLUGIN = "System.MyPlugin";
public const int STR_LEN_MED = 255;
public static UBIKClassList<MetaProperty> DefineSystemMetaProperties(UBIKEnvironment environment)
{
UBIKClassList<MetaProperty> metaProperties = new UBIKClassList<MetaProperty>();
SystemDesignMetaProxyProperty myMetaProxyProperty = new SystemDesignMetaProxyProperty(environment,
GuidUtility.MPP_MYPROPERTY, // assuming the ids are documented in a class GuidUtility
MyMetaProperties.PROPERTY_NAME_MYPROPERTY,
NAMESPACE,
PropertyTypes.String,
GuidUtility.MPP_MYPROPERTY_VIRTUAL_PROPERTIES[0],
GuidUtility.MPP_MYPROPERTY_VIRTUAL_PROPERTIES[1]);
myMetaProxyProperty.MetaAttribute = environment.GetSystemMetaClass(SystemObjects.PROXYATTRIBUTE);
myMetaProxyProperty.SetStringLen(STR_LEN_MED);
proxyProperties.Add(myMetaProxyProperty);
return metaProperties;
}
}
}
{
public class MyMetaProxyProperties
{
public const string NS_MY_PLUGIN = "System.MyPlugin";
public const int STR_LEN_MED = 255;
public static UBIKClassList<MetaProperty> DefineSystemMetaProperties(UBIKEnvironment environment)
{
UBIKClassList<MetaProperty> metaProperties = new UBIKClassList<MetaProperty>();
SystemDesignMetaProxyProperty myMetaProxyProperty = new SystemDesignMetaProxyProperty(environment,
GuidUtility.MPP_MYPROPERTY, // assuming the ids are documented in a class GuidUtility
MyMetaProperties.PROPERTY_NAME_MYPROPERTY,
NAMESPACE,
PropertyTypes.String,
GuidUtility.MPP_MYPROPERTY_VIRTUAL_PROPERTIES[0],
GuidUtility.MPP_MYPROPERTY_VIRTUAL_PROPERTIES[1]);
myMetaProxyProperty.MetaAttribute = environment.GetSystemMetaClass(SystemObjects.PROXYATTRIBUTE);
myMetaProxyProperty.SetStringLen(STR_LEN_MED);
proxyProperties.Add(myMetaProxyProperty);
return metaProperties;
}
}
}
SystemDefinitions adaptations
namespace UBIK.MyPlugin
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
// ...
#region System Meta Classes
public override UBIKClassList<MetaClass> DefineSystemMetaClasses(UBIKEnvironment environment)
{
UBIKClassList<MetaClass> metaClasses = new UBIKClassList<MetaClass>();
MyProxyMetaClass myBaseClass = new MyProxyMetaClass(environment);
metaClasses.Add(myBaseClass);
return metaClasses;
}
#endregion System Meta Classes
#region System Meta Properties
public override UBIKClassList<MetaProperty> DefineSystemMetaProperties(UBIKEnvironment environment)
{
UBIKClassList<MetaProperty> result = new UBIKClassList<MetaProperty>();
result.AddRangeUnique(MyMetaProxyProperties.DefineSystemMetaProperties(environment));
return result;
}
#endregion System Meta Properties
// ...
}
}
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
// ...
#region System Meta Classes
public override UBIKClassList<MetaClass> DefineSystemMetaClasses(UBIKEnvironment environment)
{
UBIKClassList<MetaClass> metaClasses = new UBIKClassList<MetaClass>();
MyProxyMetaClass myBaseClass = new MyProxyMetaClass(environment);
metaClasses.Add(myBaseClass);
return metaClasses;
}
#endregion System Meta Classes
#region System Meta Properties
public override UBIKClassList<MetaProperty> DefineSystemMetaProperties(UBIKEnvironment environment)
{
UBIKClassList<MetaProperty> result = new UBIKClassList<MetaProperty>();
result.AddRangeUnique(MyMetaProxyProperties.DefineSystemMetaProperties(environment));
return result;
}
#endregion System Meta Properties
// ...
}
}
Create a system classification
Here's an example for the definition of a system classification.
SystemClassification template code
namespace UBIK.MyPlugin
{
public class MyClassification : SystemClassification
{
public static Guid GUID = new Guid("aa9cc5cb-f676-4b60-b39d-eab7a8bcc66e");
public MyClassification(UBIKEnvironment environment)
: base(GUID, environment)
{
this.CodedName = "MYCLS";
this.CodedNamespace = "System.MyPlugin";
this.CodedDescription = "My classification";
// Derives from SystemDesignMetaClass, see above for metaproperty definition
}
}
}
{
public class MyClassification : SystemClassification
{
public static Guid GUID = new Guid("aa9cc5cb-f676-4b60-b39d-eab7a8bcc66e");
public MyClassification(UBIKEnvironment environment)
: base(GUID, environment)
{
this.CodedName = "MYCLS";
this.CodedNamespace = "System.MyPlugin";
this.CodedDescription = "My classification";
// Derives from SystemDesignMetaClass, see above for metaproperty definition
}
}
}
SystemDefinitions adaptations
namespace UBIK.MyPlugin
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
// ...
#region System Classifications
public override UBIKClassList<MetaClass> DefineSystemClassifications(UBIKEnvironment environment)
{
return new UBIKClassList<MetaClass>()
{
new MyClassification(environment)
};
}
#endregion System Classifications
// ...
}
}
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
// ...
#region System Classifications
public override UBIKClassList<MetaClass> DefineSystemClassifications(UBIKEnvironment environment)
{
return new UBIKClassList<MetaClass>()
{
new MyClassification(environment)
};
}
#endregion System Classifications
// ...
}
}
Create a system SelectiveList
Here's an example for the definition of a system selective list.
SystemDefinitions adaptations
namespace UBIK.MyPlugin
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
// ...
#region System Selective Lists
public override UBIKClassList<SelectiveList> DefineSystemSelectiveLists(UBIKEnvironment environment)
{
UBIKClassList<SelectiveList> selectiveLists = new UBIKClassList<SelectiveList>();
// MyEnumType should be an integer enum
SystemSelectiveList fromEnum = new SystemSelectiveList(environment, typeof(MyEnumType));
fromEnum.SetUID(GuidUtility.SLFROMENUM);
selectiveLists.Add(fromEnum);
SystemSelectiveList customList = new SystemSelectiveList(environment);
customList.SetItemValueType(PropertyTypes.String);
customList.AddSelectiveItem("any object of supported type", "description");
customList.Name = "SL_STR";
customList.SetUID(GuidUtility.SLSTR);
selectiveLists.Add(customList);
return selectiveLists;
}
#endregion System Selective Lists
// ...
}
}
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
// ...
#region System Selective Lists
public override UBIKClassList<SelectiveList> DefineSystemSelectiveLists(UBIKEnvironment environment)
{
UBIKClassList<SelectiveList> selectiveLists = new UBIKClassList<SelectiveList>();
// MyEnumType should be an integer enum
SystemSelectiveList fromEnum = new SystemSelectiveList(environment, typeof(MyEnumType));
fromEnum.SetUID(GuidUtility.SLFROMENUM);
selectiveLists.Add(fromEnum);
SystemSelectiveList customList = new SystemSelectiveList(environment);
customList.SetItemValueType(PropertyTypes.String);
customList.AddSelectiveItem("any object of supported type", "description");
customList.Name = "SL_STR";
customList.SetUID(GuidUtility.SLSTR);
selectiveLists.Add(customList);
return selectiveLists;
}
#endregion System Selective Lists
// ...
}
}
Perform pre- or postprocessing scripts
In some cases, one has to perform an action before the database is adjusted, or postprocess the upgrade. It is also possible to execute code whenever the environment is initialized, even if no upgrade was necessary.
Scripting template code
namespace UBIK.MyPlugin
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
// ...
public override void PreProcessDatabaseUpdate(Version previousVersion, UBIKEnvironment environment)
{
base.PreProcessDatabaseUpdate(previousVersion, environment);
// This code will be executed whenever the system is upgraded,
// before a schema upgrade for this SystemDefinitions package
}
public override void PostProcessDatabaseUpdate(Version previousVersion, UBIKEnvironment environment)
{
base.PostProcessDatabaseUpdate(previousVersion, environment);
// This code will be executed whenever the system is upgraded,
// after a schema upgrade and before content initialization and upgrade
// for this SystemDefinitions package
}
public override void InitializeSystemContent(UBIKEnvironment env)
{
base.InitializeSystemContent(env);
// This code will be executed whenever the system is initialized,
// after an optional schema upgrade and before an optional content adaptation
// for this SystemDefinitions package
}
public override void UpdateSystemContent(UBIKEnvironment env)
{
base.UpdateSystemContent(env);
// This code will be executed whenever the system is upgraded,
// after all other steps for this SystemDefinitions package
}
// ...
}
}
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
// ...
public override void PreProcessDatabaseUpdate(Version previousVersion, UBIKEnvironment environment)
{
base.PreProcessDatabaseUpdate(previousVersion, environment);
// This code will be executed whenever the system is upgraded,
// before a schema upgrade for this SystemDefinitions package
}
public override void PostProcessDatabaseUpdate(Version previousVersion, UBIKEnvironment environment)
{
base.PostProcessDatabaseUpdate(previousVersion, environment);
// This code will be executed whenever the system is upgraded,
// after a schema upgrade and before content initialization and upgrade
// for this SystemDefinitions package
}
public override void InitializeSystemContent(UBIKEnvironment env)
{
base.InitializeSystemContent(env);
// This code will be executed whenever the system is initialized,
// after an optional schema upgrade and before an optional content adaptation
// for this SystemDefinitions package
}
public override void UpdateSystemContent(UBIKEnvironment env)
{
base.UpdateSystemContent(env);
// This code will be executed whenever the system is upgraded,
// after all other steps for this SystemDefinitions package
}
// ...
}
}
Create a custom InterfaceAdmin
This is one of the most complex things you can do in this topic. That's because an InterfaceAdmin object has the following interesting aspects:
- It is an instance of the INTERFACE_ADMIN (Meta)MetaClass
- It is a MetaClass itself
- A custom implementation must derive from the INTERFACE_ADMIN_ROOT
- It produces special instances called InterfaceExecution
- Any functional InterfaceAdmin runtime object must be an instance of InterfaceAdministration
The last point is crucial, because this makes our task difficult. After all, we use SystemDesignMetaClass to define MetaClasses, and this directly conflicts with the last requirement. The way to solve this is to deliver a non-functional class we only use as a basis, and then derive a regular object from it.
InterfaceAdmin template code
namespace UBIK.MyPlugin
{
public class MyInterfaceAdminBase : SystemDesignMetaClass
{
public static new Guid UID = GuidUtility.INTERFACE_ADMIN_UID_BASE;
private const string NAME = "BASE_IFA";
private const string NAMESPACE = "System.MyPlugin.Interface.Administration";
private const string DESCRIPTION = "Base Class of Custom Interface Admin";
public MyInterfaceAdminBase(UBIKEnvironment environment)
{
InitUidAndEnvironment(UID, environment);
InitStrings(NAME, NAMESPACE, DESCRIPTION);
SetModuleId(MyPlugin.ID);
List<Guid> metaProperties = new List<Guid>();
DefineMetaProperties(metaProperties);
}
public override MetaClass MetaClass
{
get
{
// The current class is an instance of the Interface Admin MetaClass; an individual Interface Administration object.
return this.Environment.GetSystemMetaClass(SystemObjects.INTERFACE_ADMINISTRATION);
}
}
public override MetaClass Inheritance
{
get
{
// The current class derives from the default Interface Admin, which is also the MetaClass of all Interface Execution objects.
// Likewise, the current class is a MetaClass for Interface Execution objects.
return this.Environment.GetSystemMetaClass(SystemObjects.INTERFACE_EXECUTION);
}
set
{
throw new NotImplementedException();
}
}
public override MetaClassTypes ClassType
{
get
{
return MetaClassTypes.DEFINED_IN_PLUGIN;
}
set
{
// do nothing
}
}
public override string RuntimeTypeName => GetRuntimeType().FullName;
public override string SystemRuntimeTypeName => GetSystemRuntimeType().FullName;
public override Type GetSystemRuntimeType()
{
return typeof(MyInterfaceExecution);
}
public override Type GetRuntimeType()
{
return typeof(MyInterfaceExecution);
}
// Required for MetaClasses that have a very special MetaClass themselves
protected override MetaClass DeliverMetaMetaClassInstance()
{
return MetaClass;
}
}
}
{
public class MyInterfaceAdminBase : SystemDesignMetaClass
{
public static new Guid UID = GuidUtility.INTERFACE_ADMIN_UID_BASE;
private const string NAME = "BASE_IFA";
private const string NAMESPACE = "System.MyPlugin.Interface.Administration";
private const string DESCRIPTION = "Base Class of Custom Interface Admin";
public MyInterfaceAdminBase(UBIKEnvironment environment)
{
InitUidAndEnvironment(UID, environment);
InitStrings(NAME, NAMESPACE, DESCRIPTION);
SetModuleId(MyPlugin.ID);
List<Guid> metaProperties = new List<Guid>();
DefineMetaProperties(metaProperties);
}
public override MetaClass MetaClass
{
get
{
// The current class is an instance of the Interface Admin MetaClass; an individual Interface Administration object.
return this.Environment.GetSystemMetaClass(SystemObjects.INTERFACE_ADMINISTRATION);
}
}
public override MetaClass Inheritance
{
get
{
// The current class derives from the default Interface Admin, which is also the MetaClass of all Interface Execution objects.
// Likewise, the current class is a MetaClass for Interface Execution objects.
return this.Environment.GetSystemMetaClass(SystemObjects.INTERFACE_EXECUTION);
}
set
{
throw new NotImplementedException();
}
}
public override MetaClassTypes ClassType
{
get
{
return MetaClassTypes.DEFINED_IN_PLUGIN;
}
set
{
// do nothing
}
}
public override string RuntimeTypeName => GetRuntimeType().FullName;
public override string SystemRuntimeTypeName => GetSystemRuntimeType().FullName;
public override Type GetSystemRuntimeType()
{
return typeof(MyInterfaceExecution);
}
public override Type GetRuntimeType()
{
return typeof(MyInterfaceExecution);
}
// Required for MetaClasses that have a very special MetaClass themselves
protected override MetaClass DeliverMetaMetaClassInstance()
{
return MetaClass;
}
}
}
InterfaceExecution runtime type template code
namespace UBIK.MyPlugin.InterfaceExecutors
{
public class MyInterfaceExecution : InterfaceExecution
{
protected override IInterfaceExecutor GetExternalDataReader()
{
return new ThirdPartySystemWebAPIClientReader(Environment);
}
protected override IInterfaceExecutor GetExternalDataWriter()
{
return new ThirdPartySystemWebAPIClientWriter(Environment);
}
protected override IInterfaceExecutor GetExternalPollingExecutor()
{
return new ThirdPartySystemWebAPIClientPoller(Environment);
}
protected override IInterfaceExecutor GetExportExecutor()
{
return new MyExportExecutor(Environment);
}
protected override IInterfaceExecutor GetImportExecutor()
{
return new MyImportExecutor(Environment);
}
}
}
{
public class MyInterfaceExecution : InterfaceExecution
{
protected override IInterfaceExecutor GetExternalDataReader()
{
return new ThirdPartySystemWebAPIClientReader(Environment);
}
protected override IInterfaceExecutor GetExternalDataWriter()
{
return new ThirdPartySystemWebAPIClientWriter(Environment);
}
protected override IInterfaceExecutor GetExternalPollingExecutor()
{
return new ThirdPartySystemWebAPIClientPoller(Environment);
}
protected override IInterfaceExecutor GetExportExecutor()
{
return new MyExportExecutor(Environment);
}
protected override IInterfaceExecutor GetImportExecutor()
{
return new MyImportExecutor(Environment);
}
}
}
SystemDefinitions adaptations
namespace UBIK.MyPlugin
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
// ...
#region System Content
public override void UpdateSystemContent(UBIKEnvironment environment)
{
base.UpdateSystemContent(environment);
// Create our own custom interface admin from the base class we described.
MetaClass mc = environment.GetSystemMetaClass(SystemObjects.INTERFACE_ADMINISTRATION);
InterfaceAdministration ifa = environment.UBIKDataFactory().GetBaseObject(mc, GuidUtility.INTERFACE_ADMIN_UID_CUSTOM) as InterfaceAdministration;
if (ifa == null)
{
ifa = (InterfaceAdministration)environment.UBIKDataFactory().MetaClass(GuidUtility.INTERFACE_ADMIN_UID_BASE).CreateNewDerivate(GuidUtility.INTERFACE_ADMIN_UID_CUSTOM);
ifa.Name = "MY_IFA";
ifa.Description = "Custom Interface Admin";
ifa.Namespace = "Custom.MyPlugin.Interface.Administration";
ifa.ClassType = MetaClassTypes.Inherited;
ifa.Save();
}
Relationship relation = environment.GetSystemRelation(SystemObjects.RELATION_INTERFACE_ADMIN_METAPROXY);
MetaProxy target = (MetaProxy)environment.UBIKDataFactory().MetaClass(GuidUtility.MY_PROXY);
if(ifa.IsAddRelationAllowed(relation, target))
{
ifa.AddRelation(relation, target);
ifa.Save();
}
}
#endregion System Content
// ...
}
}
{
public class MySystemDefinitions_V100 : SystemDefinitionsBase
{
// ...
#region System Content
public override void UpdateSystemContent(UBIKEnvironment environment)
{
base.UpdateSystemContent(environment);
// Create our own custom interface admin from the base class we described.
MetaClass mc = environment.GetSystemMetaClass(SystemObjects.INTERFACE_ADMINISTRATION);
InterfaceAdministration ifa = environment.UBIKDataFactory().GetBaseObject(mc, GuidUtility.INTERFACE_ADMIN_UID_CUSTOM) as InterfaceAdministration;
if (ifa == null)
{
ifa = (InterfaceAdministration)environment.UBIKDataFactory().MetaClass(GuidUtility.INTERFACE_ADMIN_UID_BASE).CreateNewDerivate(GuidUtility.INTERFACE_ADMIN_UID_CUSTOM);
ifa.Name = "MY_IFA";
ifa.Description = "Custom Interface Admin";
ifa.Namespace = "Custom.MyPlugin.Interface.Administration";
ifa.ClassType = MetaClassTypes.Inherited;
ifa.Save();
}
Relationship relation = environment.GetSystemRelation(SystemObjects.RELATION_INTERFACE_ADMIN_METAPROXY);
MetaProxy target = (MetaProxy)environment.UBIKDataFactory().MetaClass(GuidUtility.MY_PROXY);
if(ifa.IsAddRelationAllowed(relation, target))
{
ifa.AddRelation(relation, target);
ifa.Save();
}
}
#endregion System Content
// ...
}
}
