Working with the Definition File

The definition file provides access to shared parameters.

Accessing parameters in the definition file

Use the following steps to gain access to the definition file and its parameters:

Specify the Application.SharedParametersFilename property with an existing text file or a new one.
Open the shared parameters file, using the Application.OpenSharedParameterFile() method.
Open an existing group or create a new group using the DefinitionFile.Groups property.
Open an existing external parameter definition or create a new definition using the DefinitionGroup.Definitions property.

The following classes and methods in the Autodesk.Revit.DB namespace provide access to shared parameters using the Revit API.

DefinitionFile Class
- Retrieved using the Application.OpenSharedParameterFile() method. Revit uses one shared parameter file at a time.
- Represents one shared parameter file.
- Contains a number of Group objects.
- Shared parameters are grouped for easy management and contain shared parameter definitions.
- New definitions can be added as needed.
ExternalDefinition Class
- The ExternalDefinition object is created by a DefinitionGroup object from a shared parameter file.
- External parameter definitions must belong to a Group which is a collection of shared parameter definitions.
Application.SharedParametersFilename Property
- Get and set the shared parameter file path using this property.
- By default, Revit does not have a shared parameter file.
- Initialize this property before using. If it is not initialized, an exception is thrown.

Create a Shared Parameter File

Because the definition file is a text file, it can be created manually or using code.

Code Region 22-3: Creating a shared parameter file

private void CreateExternalSharedParamFile(string sharedParameterFile)
{
        System.IO.FileStream fileStream = System.IO.File.Create(sharedParameterFile);
        fileStream.Close();
}

Access an Existing Shared Parameter File

Since Revit can have many shared parameter files, it is necessary to specifically identify the file and external parameters you want to access. The following two procedures illustrate how to access an existing shared parameter file.

Get DefinitionFile from an External Parameter File

Set the shared parameter file path as the following code illustrates, then invoke the Application.OpenSharedParameterFile() method.

Code Region 22-4: Getting the definition file from an external parameter file

private DefinitionFile SetAndOpenExternalSharedParamFile(Autodesk.Revit.ApplicationServices.Application application, string sharedParameterFile)
{
    // set the path of shared parameter file to current Revit
    application.SharedParametersFilename = sharedParameterFile;
    // open the file
    return application.OpenSharedParameterFile();
}

Note: Consider the following points when you set the shared parameter path:

During each installation, Revit cannot detect whether the shared parameter file was set in other versions. You must bind the shared parameter file for the new Revit installation again.
If Application.SharedParametersFilename is set to an invalid path, an exception is thrown only when OpenSharedParameterFile() is called.
Revit can work with multiple shared parameter files. Even though only one parameter file is used when loading a parameter, the current file can be changed freely.

Traverse All Parameter Entries

The following sample illustrates how to traverse the parameter entries and display the results in a message box.

Code Region 22-5: Traversing parameter entries

private void ShowDefinitionFileInfo(DefinitionFile myDefinitionFile)
{
    StringBuilder fileInformation = new StringBuilder(500);

    // get the file name 
    fileInformation.AppendLine("File Name: " + myDefinitionFile.Filename);

    // iterate the Definition groups of this file
    foreach (DefinitionGroup myGroup in myDefinitionFile.Groups)
    {
        // get the group name
        fileInformation.AppendLine("Group Name: " + myGroup.Name);

        // iterate the difinitions
        foreach (Definition definition in myGroup.Definitions)
        {
            // get definition name
            fileInformation.AppendLine("Definition Name: " + definition.Name);
        }
    }
    TaskDialog.Show("Revit",fileInformation.ToString());
}

Change the Parameter Definition Owner Group

The following sample shows how to change the parameter definition group owner.

Code Region 22-6: Changing parameter definition group owner

private void ReadEditExternalParam(DefinitionFile file)
{
    // get ExternalDefinition from shared parameter file
    DefinitionGroups myGroups = file.Groups;
    DefinitionGroup myGroup = myGroups.get_Item("MyGroup");
    if (myGroup != null)
    {
        ExternalDefinition myExtDef = myGroup.Definitions.get_Item("MyParam") as ExternalDefinition;
        if (myExtDef != null)
        {
            DefinitionGroup newGroup = myGroups.get_Item("AnotherGroup");
            if (newGroup != null)
            {
                // change the OwnerGroup of the ExternalDefinition
                myExtDef.OwnerGroup = newGroup;
            }
        }
    }
}