To modify a persistent object, you need do no more than set a value into one of the Persistate generated properties.  This sets a modified flag in the object, and puts the object on the list of modified objects that Persistate maintains.  Here’s an example of object modification.

foreach (Borrower borrower in The.library.Borrowers) {
   if (borrower.MaximumLendCount < 3)
      borrower.MaximumLendCount = 3;
}

This modifies the borrower objects currently retrieved from persistent storage whose MaximumLendCounts are below 3.  When the code assigns to the MaximumLendCount property, Persistate sets that object as modified and puts it on the modified list.

You can do the same with an object property.  Here are some examples

book.Author = suppliedAuthor;
book.Genre = The.Library.Genres["Biography"];
borrower.PostalAddress = newPostalAddress;

If you look at An Example Definition File, you will that the Author and Genre members are associated.  In this case the new objects are simply linked to the book as associations.  The third member PostalAddress is a contained member.  In this case, the newPostalAddress is being attached to the persistent tree, and must be a newly created object - if you try and set an existing persistent object like this, it will throw an exception.  If the PostalAddress field already contains an existing object when you set the property, then the existing object will be deleted.  To move objects from one place to another see Moving objects.

You can, if you want, modify the private fields containing the member data directly.  You might want to do this if you want to modify the object in memory without updating the object in persistent storage.  Perhaps if you have a lot of modification to do, you might want to modify the fields to save on the overhead of modifying the properties.

If you are setting field values directly, you must set the object as modified and put it on the modified list manually as follows.

myObject.SetModified();

You can do this repeatedly on the same object without problems or great overhead.  If you are calling this manually, and if the class of the object is in a category with the clone on mutate function, then you should do this before making the first modification.  The SetModified() method, when called for the first time for an object, creates a clone of that object.  This clone can be later used to restore the object – see Synchronising with persistent storage for details.  See this section also for details on committing your changes.

When you modify an object member using the generated property, Persistate raises events associated with the modification.  If you are modifying the private fields instead, you can raise these events manually as follows.

myObject.OnModified();

See the Persistent events section for details of this and other events raised by Persistate.