Introduction
One item is abstract entity and in this version of WinFS cannot be created explicitly like:
Item I = new Item();
To create a specific item (i.e. Document) use following pattern:
1. Create the instance of a specific item.
2. Set the NamespaceName property on some unique value
3. Apply attributes (optional)
4. Apply extension (optional)
5. Set the containment relationship
6. Persist changes.
Before an item can be physically (in WinFS store) creating, it has to be decided where the item will be physically stored. That means that each item needs to have one container. Theoretically, this requirement is a negative limitation, but it allows us to easier migrate our mind from common file system to the WinFS structured data.
Item Containment and Lifetime
Personally, I think that it is enough to know that one item exist in some specific store (one universe of items). That means that it is not required to know where the item is physically store it is possible to find it, when required.
Each item can have one and only one container. A container is also an item and can contain other items. For example, most popular container item is Folder. It is interesting that any item in WinFS store can be a container. To illustrate this take a look on the definition of property Children of an item:
public ContainedItemCollection Children { get; }
Each item in the WinFS store has a collection of contained items called children. The root of all items in the store can be obtained as shown in the next example:
Folder root = store.GetRootItem() as Folder;
Note that “containment” of an item defines the life time of the item. One item begins to live when it is persisted (SaveChanges) within one container. The item lives in container until it is deleted or its container is deleted.
Following example shows how to add two new documents in the root folder of the store.
using (WinFSData store = new WinFSData())
{
Document doc1 = new Document();
doc1.DisplayName = "doc1";
Document doc2 = new Document();
doc2.DisplayName = "doc2";
Folder root = store.GetRootItem() as Folder;
root.Children.Add(doc1);
root.Children.Add(doc2);
store.SaveChanges();
}
Next example show some other ways of creating of “containment” of an item. In previous example the both documents have been appended explicitly as children of the root folder.
However, an item can be also explicitly appended to the container by setting of the property ‘Container’ (see doc1 in the next example) or implicitly by creating of the instance (see doc2 in the next example).
using (WinFSData store = new WinFSData())
{
Folder root = store.GetRootItem() as Folder;
Document doc1 = new Document();
doc1.DisplayName = "doc1";
doc1.Container = root;
Document doc2 = new Document(root);
doc2.DisplayName = "doc2";
store.SaveChanges();
}
Now, let’s see how to create one document, which contains multiple documents. This is philosophically quite different than previous example, but it very common operation in WinFS. It sounds like a nonsense, but it is a very powerful feature.
Following example shows how to do that:
// Get the root item of the store.
Folder folder = store.GetRootItem() as Folder;
docContainer = new Document();
docContainer.DisplayName = "RootDoc";
docContainer.NamespaceName = "RootDoc";
docContainer.Container = folder;
//
// Create the first child document
doc1 = new Document();
doc1.DisplayName = "Child1";
doc1.NamespaceName = "Child1";
doc1.Container = docContainer;
//
// Create the second child document
doc2 = new Document();
doc2.DisplayName = "Child2";
doc2.NamespaceName = "Child2";
docContainer.Children.Add(doc2);
// Persist changes.
store.SaveChanges();
foreach (Document d in docContainer.Children.FilterByType<Document>())
Console.WriteLine(d.NamespaceName);
Following picture shows the result in the WinFS spy.
Namespace Name
By creating of an item the property NamespaceName should always be set. This property uniquely identifies the item in the store.
If it is not set by creation of the item, some default value of type GUID will be automatically set.
Think abaut this property as a human readable identifier. Please also note that additionally to NamespaeName property every item in the store also have a unique identifier property “ItemId”.
I’m not sure (not documented), but it seems that the NamespaceName is unique in the store and the itemId is unique in all stores in universe.
Next example will fail, because two items are created with the same NamespaceName property. This is the exception which will be thrown:
“Operation 'Create ComplexItems' at index 0 failed because there is already an item with the same NamespaceName exists in the store. The store error code is 24010.”
using (WinFSData store = new WinFSData())
{
Document doc1 = new Document();
doc1.NamespaceName = "123";
Document doc2 = new Document();
doc2.NamespaceName = "123";
Folder root = store.GetRootItem() as Folder;
root.Children.Add(doc1);
root.Children.Add(doc2);
store.SaveChanges();
}
For more information about WinFS, please take a look on WinFS Team blog.
Damir Dobric
Posted
Apr 15 2006, 12:37 AM
by
Damir Dobric