First, we should be clear about what we mean by moving an object.  Moving means removing an object from its current position in the persistent containment tree and adding it somewhere else.  This applies to contained member objects only, not to associated members.  Both the original and destination positions in the tree can be either scalar members or collections.  Of course, the object that you move must be of a class suitable for the destination member.

When you create, modify or delete persistent objects, you do this by manipulating instances of the generated classes directly, without the need to use any Persistate run-time API.  Moving an object from one parent object to another, on the other hand, does require an API call.  One important point to note is that when you move an object, although the object acquires a new parent, any associations to it are not broken, and continue to point to it in its new location in the tree.

The need to move objects depends on the application requirements, and some applications will never need to do it.  For example our Library sample application would probably never need this in reality, but for the sake of example, the following code moves all StockCopy objects from one Publication to another.

Publication original = The.Library.PublicationWithIsbnNumber(originalIsbn);
Publication destination = The.Library.PublicationWithIsbnNumber(destinationIsbn);
// can't use a foreach as moving will alter original collection
int count = original.StockCopies.Count;
for (int i = count - 1; i >= 0; i--)
   original.StockCopies[i].Move("StockCopies", destination, "StockCopies");

The first argument is the property name in the original parent object to move the object from, and the third argument is the property name in the destination object to move the object to.  The only requirement on these properties is that they should be for contained members, not associated, and that the destination property should be able to take the class of the moved object.  Either can be scalar or collection members.

In the above example the moved object is simply added to the destination collection.  However, there is another overload which allows you to insert into a destination collection at a particular index.  The following example inserts the first StockCopy from the source collection into the first position in the destination collection.

Publication original = The.Library.PublicationWithIsbnNumber(originalIsbn);
Publication destination = The.Library.PublicationWithIsbnNumber(destinationIsbn);
original.StockCopies[0].Move("StockCopies", destination, "StockCopies", 0);

The fourth parameter is the index to insert the object into in the destination collection.  If you use this overload and the destination is a scalar member, then the index parameter is simply ignored.