ice.NET Key Concepts: Keys

Keys are unique, string-based identifiers for Folders and Objects.

While the names of Folders and Objects do not have to be unique within one repository, there can be only one Folder and one object with the same key.

Keys are often used within a software program to retrieve a specific folder or object ("by key"). Since IDs are created by the ice.NET runtime and cannot be assumed stable between separate installations, keys provide a comfortable way to identify folders and objects in program code.

Example

This example shows how to set keys and how to retrieve objects and folders by keys.

Repository.ExecuteTransaction(delegate()
{
    // Create a folder...
    IFolder pNewFolder = Repository.RootFolder.CreateChild("Cars", "");
    
    // Create an object (within the folder)...
    IObject pNewObject = Repository.GetObjTypeByName("PDTec.ICR.SportsCar").CreateObject(pNewFolder, "Porsche 911", "");
    
    // Set a folder key...
    pNewFolder.AddKey("AllCars");
    
    // Set an object key...
    pNewFolder.AddKey("Cars.911");
});         

// Retrieve a folder by key...
IFolder pFolder1 = Repository.GetFolderByKey("AllCars");

// Retrieve a folder by key without throwing an exception on failure...
IFolder pFolder2;
if (Repository.TryGetFolderByKey("AllCars", out pFolder))
{
    // [access pFolder2]
}

// Retrieve an object by key...
IObject pObject1 = Repository.GetObjectByKey("Cars.911");

// Retrieve an object by key without throwing an exception on failure...
IObject pObject2;
if (Repository.TryGetObjectByKey("Cars.911", out pObject))
{
    // [access pObject2]
}