Initializing Leases

MarshalByRefObject instances (MBRs) can create their own lease terms, or they can be configured to use lease properties specified in the <lifetime> element of an application or machine configuration file. Setting lifetime properties work only when a lease is in its initial state, that is, when a call to InitializeLifetimeService creates it; subsequent calls will have no effect.

Overriding InitializeLifetimeService

When the ILease lease = (ILease)base.InitializeLifetimeService(); method is called in an overridden InitializeLifetimeService, either an existing lease is returned for the object, or if no lease exists, a new lease is returned. Only if a new lease is returned can the lease properties be set; you must make sure that the state is LeaseState.Initial or an exception will be thrown.

The only call that affects the lifetime service is the call to InitializeLifetimeService from the .NET remoting infrastructure, which activates the lease. Other code can call InitializeLifetimeService and create a lease, but that lease will stay in its initial state until it is returned to the .NET remoting infrastructure. An existing lease that is not in the initial state cannot be set with new values, although the new sink can return it to the infrastructure to allow multiple sinks for an object to point to the same lease.

No lease is created if the lease time is 0 (zero) or a null lease is returned. If RenewOnCallTime is 0 (zero), no sink is created but a lease will be created. The following code example demonstrates a standard override.

Public Class MyLifetimeControlObject
   Inherits MarshalByRefObject
   
   Public Overrides Function InitializeLifetimeService() As [Object]
      Dim lease As ILease = CType(MyBase.InitializeLifetimeService(), ILease)
      If lease.CurrentState = LeaseState.Initial Then
         lease.InitialLeaseTime = TimeSpan.FromMinutes(1)
         lease.SponsorshipTimeout = TimeSpan.FromMinutes(2)
         lease.RenewOnCallTime = TimeSpan.FromSeconds(2)
      End If
      Return lease
   End Function 'InitializeLifetimeService
End Class 'MyLifetimeControlObject
[C#]
public class MyLifetimeControlObject: MarshalByRefObject {
   public override Object InitializeLifetimeService()
   {
      ILease lease = (ILease)base.InitializeLifetimeService();
      if (lease.CurrentState == LeaseState.Initial)  {
         lease.InitialLeaseTime = TimeSpan.FromMinutes(1);
         lease.SponsorshipTimeout = TimeSpan.FromMinutes(2);
         lease.RenewOnCallTime = TimeSpan.FromSeconds(2);
      }
      return lease;
   }
}

The implementation of InitializeLifetimeService normally calls the corresponding method of the base class to retrieve the existing lease for the remote object. If the object has never been marshaled before, the lease returned is in its initial state and the lease properties can be set. Once the object has been marshaled, the lease goes from the initial to the active state and any attempt to initialize the lease properties will be ignored (an exception is thrown). InitializeLifetimeService is called when the remote object is activated. A list of sponsors for the lease can be supplied with the activation call and additional sponsors can be added at any time while the lease is active.

See Also

Renewing Leases | Remoting Example: Lifetimes | Lifetime Leases