In classic .NET programming, objects are referenced by assigning the object to a property. The .NET Garbage Collector removes the object from memory until there are no more references to it.

More about:

• https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/objects
• https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/new-operator
• https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/destructors
• https://docs.microsoft.com/en-us/dotnet/standard/garbage-collection/index

This concept of "fixed references" has some drawbacks related to the concept of network-transparent programming in iPlus:

1. Serialization of references: The concept of network transparent programming is based on the fact that your program code is programmed on that way that you do not have to know whether the instance you are working with is a proxy or not. As a result, references that refer to other instances (real objects) on the server side must also be available on the proxy side. Virtually an automatic transfer of references over the network (from one application domain to another).
2. Unsubscribe before Garbage-Collection: As long as a proxy instance is referenced, the server must send the values of network-enabled properties of a real instance (on the server side) to the proxy instance during change events. Conversely, if a proxy instance is no longer referenced in the client's application domain (whether by the GUI or application model), the server should stop distributing data to that proxy instance. This means before the . NET garbage collector comes into play to remove the proxy instance from memory the following task must be done before:
   • a Unsubscribe-Message must be send to the server,
   • a Deinitialisation of the Proxy-Instance must be initiated,
   • if necessary the Proxy-Instance has to be pooled.
3. Reinitialization: A classic . NET reference cannot be automatically replaced by a new object instance. However, with the concept of Reinitialization in iPlus this is absolutely necessary. A reinitialization means that a new ACComponent instance is created and replaced with an old one. In this case, all references that reference to this old instance must be replaced with the new one in the background.
4. Network transfer of database references: Classes of the entity framework also implement the interface IACObject. Because ACComponent also implements IACObject, both are an object that can be referenced and distributed across the network from an abstract perspective (see point 1). Serializing a complex entity object is basically unnecessary because the proxy instance can establish a database connection on the client side and load the data of the corresponding entity object itself.

The ACRef<T> class is an smart pointer that implements the points described earlier.

For these reasons use always the smart pointer ACRef<T> if you want to keep references to ACComponent instances for an extended period of time!

Any internal implementations in the iPlus framework are programmed to use ACRef<T>.

ACRef<T> is a generic class. The type T describes the type of object to be referencing.

The most important feature of an ACRef<T> is the state "IsAttached", which describes whether the referenced object is detached or attached. In detached state , the ACRef does not hold any . NET reference to the encapsulated object or to an instance of generic type T. Accessing the ValueT or Value property immediately reattaches the object to be rereferenced.

To ensure that an ACRef<T> in a detached state, knows which object it was connected to, either the ACUrl or the EntityKey is saved.

Essential Properties:

 public enum RefInitMode : short
 {
    NoInstantiation = 0,
    AutoStart = 1,
    AutoStop = 2,
    AutoStartStop = 3,
 }

Essential Methods:

A smart pointer is instantiated by a new statement. There are different constructors. However, you should always use the constructors where the parent object must be passed. The Parent object indicates to whom the smart pointer belongs. For references to entity objects, you pass the database context as a parent object.

References that are no longer needed must be detached using the Detach() method. Detached references can be attached using the Attach() method. For entity objects, please use the AttachTo()-Method to pass the database context.

Here are some examples:

In order for entity references to be sent over the network, they must be serialized by the DataContract serializer. Therefore, you must announce them with the ACSerializableInfo attribute class.

Conversely, if you want to know which smart pointers refer to an ACComponent (this), an ACComponent provides the IACPointReference<IACObject> ReferencePoint property.

IACPointReference is a derivation of the interface IACPoint<T>, which is a so-called connection point. An IACPoint<T> provides the IEnumerable<T> ConnectionList property, which allows you to query the ReferencePoint to get all the smart pointers related to the component:

var query = this.ReferencePoint.ConnectionList.Where(c => c is IACContainerRef);

IACContainerRef is the basic interface for the ACRef<T> class to access type-neutrally.

Because the ConnectionList of a reference point can also contain other relationships, the above query for IACContainerRef is necessary. As a rule, however, you only want to know whether the component is still being referenced or not. This provides the HasStrongReferences property:

bool hasAnyRef = this.ReferencePoint.HasStrongReferences;

This property searches the list for all smart pointers that do not have a weak reference (IsWeakReference = false).