Definition File Access

In the add-in code, complete the following steps to gain access to the definition file:

Specify the Autodesk.Revit.Options.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 list provides more information about the classes and methods in the previous diagram.

Autodesk.Revit.Parameters.DefinitionFile Class - The DefinitionFile object represents one shared parameter file.
- The object contains a number of Group objects.
- Shared parameters are grouped for easy management and contain shared parameter definitions.
- You can add new definitions as needed.
- The DefinitionFile object is retrieved using the Application.OpenSharedParameterFile method.
Autodesk.Revit.Parameters.ExternalDefinition Class - The ExternalDefinition class is derived from the Definition 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.
Autodesk.Revit.Options.Application.SharedParametersFilename Property - Get and set the shared parameter file path using the Autodesk.Revit.Options.SharedParametersFilename 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.
Autodesk.Revit.Application.OpenSharedParameterFile Method - This method returns an object representing a Revit shared parameter file.
- Revit uses one shared parameter file at a time.
- The file name for the shared parameter file is set in the Revit Application Options object. If the file does not exist, an exception is thrown.

Create a Shared Parameter File

Because the shared parameter file is a text file, you can create it using code or create it manually.

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

Because you can have many shared parameter files for Revit, 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 to app.Options.SharedParametersFilename as the following code illustrates, then invoke the Autodesk.Revit.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.Options.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 Options.SharedParametersFilename is set to a wrong 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 (null == myGroup)
                return;
 
        Definitions myDefinitions = myGroup.Definitions;
        ExternalDefinition myExtDef =
                                                        myDefinitions.get_Item("MyParam") as ExternalDefinition;
        if (null == myExtDef)
                return;

        StringBuilder strBuilder = new StringBuilder();
        // iterate every property of the ExternalDefinition
        strBuilder.AppendLine("GUID: " + myExtDef.GUID.ToString())
                .AppendLine("Name: " + myExtDef.Name)
                .AppendLine("OwnerGroup: " + myExtDef.OwnerGroup.Name)
                .AppendLine("Parameter Group" + myExtDef.ParameterGroup.ToString())
                .AppendLine("Parameter Type" + myExtDef.ParameterType.ToString())
                .AppendLine("Is Visible: " + myExtDef.Visible.ToString());

        TaskDialog.Show("Revit", strBuilder.ToString());

        // change the OwnerGroup of the ExternalDefinition
        myExtDef.OwnerGroup = myGroups.get_Item("AnotherGroup");
}