GlobalParameter Basics

The GlobalParameter class represents a global parameter in a project document and can be used to create and modify global parameters.

Creating global parameters

Global parameters may be created only in project documents, not in families. Global parameters are created via the static Create() method in a given document, with a given name and ParameterType. Each new parameter must have a name that is unique within the document, which can be determined using the static GlobalParametersManager.IsUniqueName() method. Global parameters can be created with almost any type of data, but there are a few types that are not currently supported, such as the ElementId type. Test whether a particular data type is appropriate for a global parameter by using the static GlobalParameter.IsValidDataType() method.

Parameters are created as non-reporting initially, but can be changed after creation using the IsReporting property if the global parameter is of an eligible type. See the Reporting vs. Non-Reporting Parameters page for more information.

Code Region: Create a new global parameter 

/// <summary>
/// Creates a new Global Parameter of type Length, assigns it an initial value,
/// and uses it to label a set of input dimension elements.
/// </summary>
/// <param name="document">Revit project document in which to create the parameter.</param>
/// <param name="name">Name of the global parameter to create.</param>
/// <param name="value">A value the new global parameter is to have.</param>
/// <param name="dimensionsToLabel">A set of dimension to labe by the new global parameter.</param>
/// <returns>ElementId of the new GlobalParameter</returns>
public ElementId CreateNewGlobalParameter(Document document, String name, double value, ISet<ElementId> dimensionsToLabel)
{
    if (!GlobalParametersManager.AreGlobalParametersAllowed(document))
        throw new System.InvalidOperationException("Global parameters are not permitted in the given document");

    if (!GlobalParametersManager.IsUniqueName(document, name))
        throw new System.ArgumentException("Global parameter with such name already exists in the document", "name");

    ElementId gpid = ElementId.InvalidElementId;

    // creation of any element must be in a transaction
    using (Transaction trans = new Transaction(document, "Create Global Parameter"))
    {
        trans.Start();

        // create a GP with the given name and type Length
        GlobalParameter gp = GlobalParameter.Create(document, name, ParameterType.Length);
        if (gp != null)
        {
            // if created successfully, assign it a value
            // note: parameters of type Length accept Double values
            gp.SetValue(new DoubleParameterValue(value));

            // if a collection of dimensions was given, label them with this new parameter
            foreach (ElementId elemid in dimensionsToLabel)
            {
                // not just any dimension is allowed to be labeled
                // check first to avoid exceptions
                if (gp.CanLabelDimension(elemid))
                {
                    gp.LabelDimension(elemid);
                }
            }

            gpid = gp.Id;
        }
        trans.Commit();
    }

    return gpid;
}

Getting and setting the value of a global parameter

All global parameters, formula-driven, dimension-driven, or independent, have values. A value can be obtained by calling the GetValue() method. The object returned by that method is an instance of one of the classes derived from the ParameterValue class:

All the derived classes have only one property, Value, which gets or sets the value as the corresponding type.

The concrete instance is determined by the type of the global parameter which was specified upon creation. Parameters that are neither formula-driven nor dimension-driven (reporting) can have a value assigned. The method to use is SetValue() and it accepts the same type of ParameterValue that is returned by GetValue(). However, the type can also be deduced easily: Text parameters accept only StringParameterValue. Integer and YesNo parameters accept only IntegerParameterValue. All other parameters accept only DoubleParameterValue.

Elements affected by a global parameter

Global parameters can be associated with other global parameters as well as regular family instance parameters (which may report global parameters as their values via the assignment formula.) There are two methods available to find relations among parameters: GlobalParameter.GetAffectedGlobalParameters() and GlobalParameter.GetAffectedElements(). The former returns all other global parameters that refer to a particular global parameter in their respective formulas. The latter method returns a set of all elements of which some parameters are controlled by the global parameter. These two methods together with the GlobalParameter.GetLabeledDimensions() can help determine out how model elements relate to each other via global parameters.

Methods for maintaining associations between element properties and global parameters can be found in the Parameter class.

Parent topic: Global Parameters