' <summary>
' Creates a global parameter and uses it to label the set of given dimension elements 
' </summary>
' <param name="document">Revit project document that contains the dimension.</param>
' <param name="gpname">A name of the global parameter to create.</param>
' <param name="value">Initial value of the global parameter</param>
' <param name="dimset">A collection of dimension elements to drive by a global parameter</param>
' <returns>Number of actually labeled dimension</returns>
Public Function DriveSelectedDimensions(document As Document, name As String, value As Double, dimset As ISet(Of ElementId)) As Integer
    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

    If value <= 0.0 Then
        Throw New System.ArgumentException("Value of a global parameter that drives dimension must be a positive number", "value")
    End If

    Dim nLabeledDims As Integer = 0
    ' number of labeled dimensions (for testing)
    ' 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
        ' Note: Length (or Angle) is required type of global parameters that are to label a dimension
        Dim newgp As GlobalParameter = GlobalParameter.Create(document, name, ParameterType.Length)
        If newgp IsNot Nothing Then
            newgp.SetValue(New DoubleParameterValue(value))

            ' use the parameter to label the given dimensions
            For Each elemid As ElementId In dimset
                ' not just any dimension is allowed to be labeled
                ' check first to avoid exceptions
                If newgp.CanLabelDimension(elemid) Then
                    newgp.LabelDimension(elemid)
                    nLabeledDims += 1
                End If
            Next

            trans.Commit()
        End If
    End Using

    ' for illustration purposes only, we'll test the results of our modifications 


    ' 1.) Check the new parameter can be found


    Dim gpid As ElementId = GlobalParametersManager.FindByName(document, name)
    If gpid = ElementId.InvalidElementId Then
        TaskDialog.Show("Error", "Failed to find a newly created global parameter")
    End If

    Dim gp As GlobalParameter = TryCast(document.GetElement(gpid), GlobalParameter)

    ' 2. Check the number of labeled dimension is as expected


    Dim labeledSet As ISet(Of ElementId) = gp.GetLabeledDimensions()
    If labeledSet.Count <> nLabeledDims Then
        TaskDialog.Show("Error", "Have not found all the dimension that were labeled.")
    End If

    Return labeledSet.Count
End Function