Create Method


Creates a new Global Parameter in the given document.

Namespace: Autodesk.Revit.DB
Assembly: RevitAPI (in RevitAPI.dll) Version: 17.0.0.0 (17.0.1090.0)
Since: 2016 Subscription Update

Syntax

C#
public static GlobalParameter Create(
	Document document,
	string name,
	ParameterType datatype
)
Visual Basic
Public Shared Function Create ( _
	document As Document, _
	name As String, _
	datatype As ParameterType _
) As GlobalParameter
Visual C++
public:
static GlobalParameter^ Create(
	Document^ document, 
	String^ name, 
	ParameterType datatype
)

Parameters

document
Type: Autodesk.Revit.DB Document
Document in which the new parameter is to be created
name
Type: System String
The name of the new parameter. It must be unique in the document
datatype
Type: Autodesk.Revit.DB ParameterType
Type of the data the parameter is to store

Return Value

An instance of the new global parameter

Remarks

Global parameters may be created only in Project documents, not in families.

Each global parameter must have a valid name that is unique within the document. To test whether a name is unique, use the IsUniqueName(Document, String) method.

While global parameters can be created with almost any type of data, there is a few types that are not currently supported, such as the ElementId type. Programmers can test whether a particular data type is appropriate for a global parameter by using the IsValidDataType(ParameterType) method.

Parameters are created as non-reporting initially, but programmers are free to modify the IsReporting property once a global parameter is created and happens to be of a type eligible for reporting.

Examples

Copy C#
/// <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;
}
Copy VB.NET
' <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 Function CreateNewGlobalParameter(document As Document, name As [String], value As Double, dimensionsToLabel As ISet(Of ElementId)) As ElementId
    If Not GlobalParametersManager.AreGlobalParametersAllowed(document) Then
        Throw New System.InvalidOperationException("Global parameters are not permitted in the given document")
    End If

    If Not GlobalParametersManager.IsUniqueName(document, name) Then
        Throw New System.ArgumentException("Global parameter with such name already exists in the document", "name")
    End If

    Dim gpid As ElementId = ElementId.InvalidElementId

    ' creation of any element must be in a transaction
    Using trans As New Transaction(document, "Create Global Parameter")
        trans.Start()

        ' create a GP with the given name and type Length
        Dim gp As GlobalParameter = GlobalParameter.Create(document, name, ParameterType.Length)
        If gp IsNot Nothing Then
            ' 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
            For Each elemid As ElementId In dimensionsToLabel
                ' not just any dimension is allowed to be labeled
                ' check first to avoid exceptions
                If gp.CanLabelDimension(elemid) Then
                    gp.LabelDimension(elemid)
                End If
            Next

            gpid = gp.Id
        End If
        trans.Commit()
    End Using

    Return gpid
End Function

Exceptions

Exception Condition
Autodesk.Revit.Exceptions ArgumentException Global parameters are not supported in the given document. A possible cause is that it is not a project document, for global parameters are not supported in Revit families. -or- name is an empty string. -or- name cannot include prohibited characters. -or- A global parameter with the given name already exists in the document. -or- The given datatype is not valid type of data for a global parameter.
Autodesk.Revit.Exceptions ArgumentNullException A non-optional argument was NULL
Autodesk.Revit.Exceptions ArgumentOutOfRangeException A value passed for an enumeration argument is not a member of that enumeration

See Also