| API Documentation: | ExtraPropertiesExtension |
|---|
Additional, ad-hoc, properties for Gradle domain objects.
Extra properties extensions allow new properties to be added to existing domain objects. They act like maps,
allowing the storage of arbitrary key/value pairs. All ExtensionAware Gradle domain objects intrinsically have an extension
named “ext” of this type.
An important feature of extra properties extensions is that all of its properties are exposed for reading and writing via the ExtensionAware
object that owns the extension.
project.ext.set("myProp", "myValue") assert project.myProp == "myValue" project.myProp = "anotherValue" assert project.myProp == "anotherValue" assert project.ext.get("myProp") == "anotherValue"
Extra properties extension objects support Groovy property syntax. That is, a property can be read via extension.«name» and set via
extension.«name» = "value". Wherever possible, the Groovy property syntax should be preferred over the
ExtraPropertiesExtension.get() and ExtraPropertiesExtension.set() methods.
project.ext {
myprop = "a"
}
assert project.myprop == "a"
assert project.ext.myprop == "a"
project.myprop = "b"
assert project.myprop == "b"
assert project.ext.myprop == "b"You can also use the Groovy accessor syntax to get and set properties on an extra properties extension.
project.ext["otherProp"] = "a" assert project.otherProp == "a" assert project.ext["otherProp"] == "a"
The exception that is thrown when an attempt is made to get the value of a property that does not exist is different depending on whether the
Groovy syntax is used or not. If Groovy property syntax is used, the Groovy MissingPropertyException will be thrown.
When the ExtraPropertiesExtension.get() method is used, an UnknownPropertyException will be thrown.
| Property | Description |
properties | Returns all of the registered properties and their current values as a map. The returned map is detached from the extension. That is, any changes made to the map do not change the extension from which it originated. |
| Method | Description |
get(name) | Returns the value for the registered property with the given name. When using an extra properties extension from Groovy, you can also get properties via Groovy's property syntax. All of the following lines of code are equivalent. |
has(name) | Returns whether or not the extension has a property registered via the given name. |
set(name, value) | Updates the value for, or creates, the registered property with the given name to the given value. When using an extra properties extension from Groovy, you can also set properties via Groovy's property syntax. All of the following lines of code are equivalent. |
Returns all of the registered properties and their current values as a map. The returned map is detached from the extension. That is, any changes made to the map do not change the extension from which it originated.
project.version = "1.0" assert project.hasProperty("version") assert project.ext.properties.containsKey("version") == false project.ext.foo = "bar" assert project.ext.properties.containsKey("foo") assert project.ext.properties.foo == project.ext.foo assert project.ext.properties.every { key, value -> project.properties[key] == value }
Returns the value for the registered property with the given name. When using an extra properties extension from Groovy, you can also get properties via Groovy's property syntax. All of the following lines of code are equivalent.
project.ext { foo = "bar" }
assert project.ext.get("foo") == "bar"
assert project.ext.foo == "bar"
assert project.ext["foo"] == "bar"
assert project.foo == "bar"
assert project["foo"] == "bar"
When using the first form, an UnknownPropertyException exception will be thrown if the
extension does not have a property called “foo”. When using the second forms (i.e. Groovy notation),
Groovy's MissingPropertyException will be thrown instead.
boolean has(String name)
Returns whether or not the extension has a property registered via the given name.
assert project.ext.has("foo") == false assert project.hasProperty("foo") == false project.ext.foo = "bar" assert project.ext.has("foo") assert project.hasProperty("foo")
Updates the value for, or creates, the registered property with the given name to the given value. When using an extra properties extension from Groovy, you can also set properties via Groovy's property syntax. All of the following lines of code are equivalent.
project.ext.set("foo", "bar") project.ext.foo = "bar" project.ext["foo"] = "bar" // Once the property has been created via the extension, it can be changed by the owner. project.foo = "bar" project["foo"] = "bar"