Update README.md (#16)

pull/18/head
Chris Kuech 2019-07-04 23:41:25 -04:00 committed by GitHub
parent f5e36ea510
commit 7f675f361d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 24 additions and 0 deletions

View File

@ -1,6 +1,8 @@
# Requirements
Requirements is a PowerShell Gallery module for declaratively describing a system as a set of "requirements", then idempotently setting each requirement to its desired state.
The background motivation and implementation design are discussed in detail in [Declarative Idempotency](https://itnext.io/declarative-idempotency-aaa07c6dd9a0?source=friends_link&sk=f0464e8e29525b23aabe766bfb557dd7).
## Usage
We use the term `Test` to refer to the condition that describes whether the Requirement is in its desired state. We use the term `Set` to refer to the command that a `Requirement` uses to put itself in its desired state if it is known to not be in its desired state.
@ -43,6 +45,28 @@ $requirements = @(
)
```
#### Validation Requirements
If you wish to assert that a precondition is met before continuing, you can leave out the `Set` block. This is useful for [Defensive programming](https://itnext.io/defensive-powershell-with-validation-attributes-8e7303e179fd?source=friends_link&sk=14765ca9554709a77f8af7d73612ef5b), or when a Requirement requires manual steps.
```powershell
@{
Name = "Resource 1"
Describe = "Azure CLI is authenticated"
Test = { az account }
}
```
#### Idempotent `Set` blocks
Sometimes, your `Set` block is already idempotent and an associated `Test` block cannot be defined. In this case, you can leave out the `Test` block.
```powershell
@{
Name = "Resource 1"
Describe = "Initial state of system is backed up"
Set = { Get-StateOfSystem | Out-File "$BackupContainer/$(Get-Date -Format 'yyyyMMddhhmmss').log" }
]
```
### Idempotently Setting requirements
Simply pipe an array of `Requirement`s to `Invoke-Requirement`