Class Tag

Namespace

L5Sharp.Components

Assembly

L5Sharp.dll

A logix Tag component. Contains the properties that comprise the L5X Tag element.

public class Tag : LogixComponent<Tag>, ILogixSerializable

Inheritance

object

LogixElement

LogixComponent<Tag>

Tag

Implements

ILogixSerializable

Derived

LocalTag

Inherited Members

LogixComponent<Tag>.Use

LogixComponent<Tag>.AddAfter(Tag)

LogixComponent<Tag>.AddBefore(Tag)

LogixComponent<Tag>.Clone()

LogixComponent<Tag>.Remove()

LogixComponent<Tag>.Replace(Tag)

LogixElement.Element

LogixElement.IsAttached

LogixElement.Clone<TElement>()

LogixElement.L5X()

LogixElement.Serialize()

LogixElement.GetValue<T>(string)

LogixElement.GetValue<T>(Func<XElement, XElement>, string)

LogixElement.GetValue<T>(XName, string)

LogixElement.GetRequiredValue<T>(string)

LogixElement.GetProperty<T>(string)

LogixElement.GetComplex<T>(string)

LogixElement.GetContainer<TChild>(string)

LogixElement.GetDateTime(string, string)

LogixElement.SetValue<T>(T, string)

LogixElement.SetValue<T>(T, Func<XElement, XElement>, string)

LogixElement.SetValue<T>(T, XName, string)

LogixElement.SetRequiredValue<T>(T, string)

LogixElement.SetProperty<T>(T, string)

LogixElement.SetComplex<T>(T, string)

LogixElement.SetContainer<TChild>(LogixContainer<TChild>, string)

LogixElement.SetDateTime(DateTime?, string, string)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Constructors

Tag()

Creates a new Tag with default values.

public Tag()

Tag(XElement)

Creates a new Tag initialized with the provided XElement.

public Tag(XElement element)

Parameters

element XElement

The XElement to initialize the type with.

Exceptions

ArgumentNullException

element is null.

Properties

AliasFor

The tag name of the tag that is the alias of the current tag object.

public TagName? AliasFor { get; set; }

Property Value

TagName

A TagName string representing the full tag name of the alias tag.

Constant

Indicates whether the tag is a constant.

public bool? Constant { get; set; }

Property Value

bool?

true if the tag is constant; otherwise, false.

Remarks

Only value type tags have the ability to be set as a constant. Default is false.

DataType

The name of the data type the tag represents.

public string DataType { get; }

Property Value

string

A string representing the name of the tag data type.

Remarks

This property simply points to the name property of Value. This keeps the properties in sync. By initializing value, you are setting the data type name. Once initialized, the data type won't change. To change the tag's type, use With(LogixType).

Description

The description (either root, comment, or parent) for the tag or tag member.

public override string? Description { get; set; }

Property Value

string

A string containing the text description for the tag.

Remarks

If this is the root tag, this will return the root/base description. If this is a nested tag member, this will look for a configured comment (as comments are stored in a different element in the L5X), and return the value if found. If the comment is not found for the tag member, this will return the parent description, which mimics the pass through feature of logix tag documentation.

Setting this value for a nested tag member will update the underlying comments element for the tag. Setting this value for the root tag will simply update the root tag description element.

Dimensions

The dimensions of the tag, indicating the length and dimensions of it's array.

public Dimensions Dimensions { get; }

Property Value

Dimensions

A Dimensions value representing the array dimensions of the tag.

Remarks

This value will always point to the dimensions property of Value, assuming it is an ArrayType. If Value is not an array type, this property will always return Empty.

ExternalAccess

The external access option indicating the read/write access of the tag.

public ExternalAccess? ExternalAccess { get; set; }

Property Value

ExternalAccess

A ExternalAccess option representing read/write access of the tag.

this[TagName]

Gets the tag member having the provided tag name value. The tag name can represent either an immediate member or a nested member in the tag hierarchy.

public Tag this[TagName tagName] { get; }

Parameters

tagName TagName

The TagName relative to the current tag member for which to retrieve.

Property Value

Tag

A child Tag component represented by the provided tag name value.

Remarks

Note that tagName can be a path to a member more than one layer down the hierarchical structure of the tag. However, it must start with a member of the current tag, and not the actual name of this tag object. The difference between this indexer property and Member(TagName) is that this will throw and exception if a member with tagName is not found (i.e. returns non-nullable reference type).

Exceptions

ArgumentNullException

tagName is null.

ArgumentException

tagName does not represent a valid member for the tag member data structure.

Name

The unique name of the component.

public override string Name { get; set; }

Property Value

string

A string representing the component name.

Remarks

The name servers as a unique identifier for various types of components. In most cases, the component name should satisfy Logix naming constraints of alphanumeric and underscore ('_') characters, start with a letter, and be between 1 and 40 characters. Validation is not performed by this library, so importing components with invalid names may fail.

Parent

The parent tag of this Tag member.

public Tag? Parent { get; }

Property Value

Tag

A Tag representing the immediate parent tag of the this tag member. Will be null for all root tag objects.

Remarks

This property helps model the hierarchical structure of a tag object. Tags has a Value which can represent a nested complex data type. This class models this by keeping references to the Root and Parent tags for each tag object. Only nested tag members should have a Parent.

See Also

Root

Radix

The radix format of Value. Only applies if the tag is an AtomicType.

public Radix Radix { get; }

Property Value

Radix

A Radix option representing data format of the tag value.

Remarks

This value will always point to the radix of Value, assuming it is an AtomicType. If Value is not an atomic type, this property will always return Null.

Root

The root tag of this Tag member.

public Tag Root { get; }

Property Value

Tag

A Tag representing the root tag.

Remarks

This property helps model the hierarchical structure of a tag object. Tags has a Value which can represent a nested complex data type. This class models this by keeping references to the Root and Parent tags for each tag object. All tags should have a Root.

See Also

Parent

Scope

The scope type of the tag component, indicating whether the tag is a global controller tag, a local program tag. or neither.

public Scope Scope { get; }

Property Value

Scope

A Scope option indicating the container type for the tag.

Remarks

The scope of a tag component is determined from the ancestors of the underlying element. If the first parent is program element, the tag is program scoped. If the first element is a controller element, the tag is controller scoped. If ancestors of these types are not found, we assume the tag has no/null scope.

This property is not inherent in the L5X of the tag component, but one that adds a lot of value as it helps identify tags within the L5X file. This is why it is part of the core component model.

TagName

The full tag name path of the Tag.

public TagName TagName { get; }

Property Value

TagName

A TagName containing the full dot-down path of the tag member name.

Remarks

This property will always represent the fully qualified tag name path, which includes nested tag member object. This property is determined using the hierarchical structure of the tag component.

TagType

A type indicating whether the current tag component is a base tag, or alias for another tag instance.

public TagType? TagType { get; set; }

Property Value

TagType

A TagType option representing the type of tag component.

Unit

The configured unit value of the tag.

public string? Unit { get; set; }

Property Value

string

A string representing the defined units of the tag.

Remarks

This appears only used for module defined tags.

Usage

The usage option indicating the scope in which the tag is visible or usable from.

public TagUsage? Usage { get; set; }

Property Value

TagUsage

A TagUsage option representing the tag scope.

Value

The value or data of the Tag.

public LogixType Value { get; set; }

Property Value

LogixType

A LogixType containing the tag data.

Remarks

The LogixType is the basis for all tag data types. This property may represent the atomic value (bool, integer, float), string, complex structure, or array. LogixType has built in implicit operators to convert .NET types to LogixType objects so to make setting Value more concise.

Since the type can not be known at compile time when deserializing, we treat it as the abstract base class. However, the LogixSerializer will attempt to create concrete instances of types that are available, allowing the user to cast Value down to more derived types.

Methods

Member(TagName)

Gets a descendent tag member relative to the current tag member.

public Tag? Member(TagName tagName)

Parameters

tagName TagName

The full TagName path of the member to get.

Returns

Tag

A Tag representing the child member instance.

Examples

var member = tag.Member("Array[1].SubType.Member.0");

Remarks

Note that tagName can be a path to a member more than one layer down the hierarchical structure of the tag or tag member. However, it must start with a member of the current tag or tag member, and not the actual name of the current tag or tag member.

Members()

Gets this and all descendent tag members of the tag data structure.

public IEnumerable<Tag> Members()

Returns

IEnumerable<Tag>

A IEnumerable<T> containing Tag objects.

Remarks

This recursively traverses the hierarchical data structure of tag's Value and returns all descendant tags, as well as this tag.

Members(Predicate<TagName>)

Gets this and all descendent tag members of the tag data structure that satisfy the specified tag name predicate.

public IEnumerable<Tag> Members(Predicate<TagName> predicate)

Parameters

predicate Predicate<TagName>

A predicate expression specifying the tag name filter.

Returns

IEnumerable<Tag>

A IEnumerable<T> containing Tag objects that satisfy the predicate.

Remarks

This recursively traverses the hierarchical data structure of tag's Value and returns all tags that satisfy the specified predicate.

Members(Predicate<Tag>)

Gets this and all descendent tag members of the tag data structure that that satisfy the specified tag predicate.

public IEnumerable<Tag> Members(Predicate<Tag> predicate)

Parameters

predicate Predicate<Tag>

A predicate expression specifying the tag filter.

Returns

IEnumerable<Tag>

A IEnumerable<T> containing Tag objects that satisfy the predicate.

Remarks

This recursively traverses the hierarchical data structure of tag's Value and returns all tags that satisfy the specified predicate.

MembersOf(TagName)

Gets all descendent tags of the tag specified by the provided tag name.

public IEnumerable<Tag> MembersOf(TagName tagName)

Parameters

tagName TagName

A tag name path to the tag member for which to get members of.

Returns

IEnumerable<Tag>

A IEnumerable<T> containing Tag objects.

Remarks

This recursively traverses the hierarchical data structure of the tag and returns all child/descendant members.

New<TLogixType>(string)

Creates a new Tag with the provided name and specified type parameter.

public static Tag New<TLogixType>(string name) where TLogixType : LogixType, new()

Parameters

name string

The name of the tag.

Returns

Tag

A new Tag object with specified parameters.

Type Parameters

TLogixType

The logix data type of the tag. Type must have parameterless constructor to create.

ToString()

Returns a string that represents the current object.

public override string ToString()

Returns

string

A string that represents the current object.

Remarks

This override returns the component name of the type.

With(LogixType)

Returns as new Tag with the updated data type value provided.

public Tag With(LogixType value)

Parameters

value LogixType

The LogixType value to change to.

Returns

Tag

A Tag with the same underlying XElement and corresponding properties with Value changed to the provided LogixType.

Remarks

This is meant to be a concise way to change the data type of tag while leaving all else the same, since setting Value should only ever update the value and not change the data type.

If this is called for the Root tag object, then the entire data element is replaced and a new instance is returned. The Tag will still be attached as we are mutating the underlying element object in place. If this is called for a nested tag member, then this method checks if the parent tag is a complex type, and if so, calls the underlying Replace method for the current member name. Therefore, calls to this method for nested tags will fail if Value for the parent tag is not a complex type object.

Exceptions

InvalidOperationException

When this tag is a nested tag member and it's parent tag's Value property is not a ComplexType object.