[//]: # (TOC Begin)

• Introduction
• Naming rules
• Built-in properties
  • Framework-related properties
  • Platform-related properties
• Read-only properties
• Global properties
• Examples

[//]: # (TOC End)

Introduction

A project can have a set of properties. These might be set in the buildfile by the <property> task, or might be set outside NAnt. A property has a name and a value. Properties may be used in the value of task attributes. This is done by placing the property name between "${" and "}" in the attribute value. Properties may also be used in <expressions>.

Naming rules

A property name is a string of the following characters:

• letters (A-Z, a-z),
• digits (0-9),
• underscore characters (_),
• dash characters (-),
• dot characters (.),

In addition, a valid property name must start with a letter or an underscore and must end with a letter, digit or an uderscore.

Examples of valid property names include:

• propertyname
• property.name.with.dots
• property-name-with-dashes
• property.name-with.both-dots.and-dashes
• __prop---3-erty__
• __prop.1...erty__
• property1
• property1.0
• property2.0.0
• property-2-1_
• property-1-name_
• property-1.0-name

The following property names are not valid in NAnt:

• !@#!@$!@ (contains illegal characters)
• .aaaaa (starts with a dot)
• -aaaaa (starts with a dash)
• 1aaaaa (starts with a digit)
• aaaaa.aaa.a.a.a.a- (ends with a dash)
• aaaaa.aaa.a.a.a.a. (ends with a dot)

Built-in Properties

NAnt has these built-in properties:

Framework related Properties

Platform related Properties

Read-only Properties

A property can be explicitly marked read-only by setting the "readonly" attribute on the <property> task to true.

The value of a read-only property cannot be modified after it has been set.

When attempting to override a read-only property using the <property> task, the new value will be ignored and a warning message will be output in the build log. Attempting to override read-only properties using any other means (eg. other tasks) will result in a build failure.

Note: properties set on the command-line are always read-only.

Global Properties

Properties that should be accessible to all build files on a system can be defined in the <properties> node of the NAnt configuration file (NAnt.exe.config).

By changing the value of the property in the NAnt configuration file, the updated value will be accessible to all build files on the system:

    <?xml version="1.0"?>
    <configuration>
        ...
        <nant>
            ...
            <properties>
                <!-- properties defined here are accessible to all build files -->
                <property name="company.name" value="Foo Ltd." readonly="true" />
            </properties>
        </nant>
    </configuration>

Individual build files can then use this property:

    <?xml version="1.0"?>
    <project name="test">
        <echo message="Company: ${company.name}" />
    </project>

The output of this build is:

[echo] Company: Foo Ltd.

Examples

The following build file demonstrates the use of property expansion:

    <?xml version="1.0"?>
    <project name="Property Test" default="test" basedir=".">
        <property name="project.name" value="PropertyTest"/>
        <property name="project.version" value="1.0.0"/>
        <target name="test">
            <echo message="Building ${project.name}-${project.version}"/>
        </target>
    </project>

The output of this build is:

[echo] Building PropertyTest-1.0.0

The following build file demonstrates the use of properties in <expressions>. It evaluates the length of the property project.name and displays it.

    <?xml version="1.0"?>
    <project name="Expression Test" default="test" basedir=".">
        <property name="project.name" value="Expression Test"/>
        <target name="test">
            <echo message="Project name consists of ${string::get-length(project.name)} characters."/>
        </target>
    </project>

The output of this build is:

[echo] Project name consists of 15 characters.

See Also

• <property>
• <sysinfo>
• <tstamp>