diff --git a/docs/reference/schemas/config/functions/endsWith.md b/docs/reference/schemas/config/functions/endsWith.md new file mode 100644 index 000000000..2cafddfae --- /dev/null +++ b/docs/reference/schemas/config/functions/endsWith.md @@ -0,0 +1,181 @@ +--- +description: Reference for the 'endsWith' DSC configuration document function +ms.date: 08/12/2025 +ms.topic: reference +title: endsWith +--- + +# endsWith + +## Synopsis + +Determines whether a string ends with the specified suffix. + +## Syntax + +```Syntax +endsWith(, ) +``` + +## Description + +The `endsWith()` function returns `true` if the first string ends with the +specified suffix. Comparison is case-sensitive. Use it for conditional logic in +configuration documents such as matching file extensions, environment name +suffixes, or resource identifiers. + +## Examples + +### Example 1 - Check a file extension + +The following example checks if a specified filename ends with `.log`. + +```yaml +# endswith.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + fileName: + type: string + defaultValue: application.log +resources: +- name: Check file extension + type: Microsoft.DSC.Debug/Echo + properties: + output: + isLog: "[endsWith(parameters('fileName'), '.log')]" +``` + +```bash +dsc config get --file endswith.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Check file extension + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + isLog: true +messages: [] +hadErrors: false +``` + +### Example 2 - Conditional environment handling + +The following example uses `endsWith()` to build a message when an environment +name ends with `-prod`. + +```yaml +# endswith.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + environment: + type: string + defaultValue: web-prod +resources: +- name: Environment classification + type: Microsoft.DSC.Debug/Echo + properties: + output: + classification: "[if(endsWith(parameters('environment'), '-prod'), 'Production', 'Non-production')]" +``` + +```bash +dsc config get --file endswith.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Environment classification + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + classification: Production +messages: [] +hadErrors: false +``` + +### Example 3 - Filter resource identifiers + +The following example shows checking multiple suffixes by combining conditions. + +```yaml +# endswith.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + resourceId: + type: string + defaultValue: storage-westus-01 +resources: +- name: Identify resource segment + type: Microsoft.DSC.Debug/Echo + properties: + output: + isRegional: "[endsWith(parameters('resourceId'), '-01')]" + endsWithWest: "[endsWith(parameters('resourceId'), 'westus-01')]" + endsWithEast: "[endsWith(parameters('resourceId'), 'eastus-01')]" +``` + +```bash +dsc config get --file endswith.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Identify resource segment + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + isRegional: true + endsWithWest: true + endsWithEast: false +messages: [] +hadErrors: false +``` + +## Parameters + +### string + +The input string to evaluate. + +```yaml +Type: string +Required: true +Position: 1 +``` + +### suffix + +The suffix string to test for. + +```yaml +Type: string +Required: true +Position: 2 +``` + +## Output + +The `endsWith()` function returns a boolean value indicating whether the input +string ends with the specified suffix. + +```yaml +Type: bool +``` + +## Related functions + +- [`startsWith()`][00] - Determines whether a string starts with a prefix +- [`concat()`][01] - Concatenates strings together +- [`if()`][02] - Returns values based on a condition +- [`string()`][03] - Converts values to strings + + +[00]: ./startsWith.md +[01]: ./concat.md +[02]: ./if.md +[03]: ./string.md diff --git a/docs/reference/schemas/config/functions/startsWith.md b/docs/reference/schemas/config/functions/startsWith.md new file mode 100644 index 000000000..233bb4d1d --- /dev/null +++ b/docs/reference/schemas/config/functions/startsWith.md @@ -0,0 +1,181 @@ +--- +description: Reference for the 'startsWith' DSC configuration document function +ms.date: 08/12/2025 +ms.topic: reference +title: startsWith +--- + +# startsWith + +## Synopsis + +Determines whether a string starts with the specified prefix. + +## Syntax + +```Syntax +startsWith(, ) +``` + +## Description + +The `startsWith()` function returns `true` if the first string starts with the +specified prefix. Comparison is case-sensitive. Use it for conditional logic in +configuration documents such as grouping resource names, validating identifiers, +or routing operations based on naming conventions. + +## Examples + +### Example 1 - Validate resource naming convention + +The following example checks if a resource name follows a standard prefix. + +```yaml +# startswith.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + resourceName: + type: string + defaultValue: svc-api-west +resources: +- name: Resource naming check + type: Microsoft.DSC.Debug/Echo + properties: + output: + hasSvcPrefix: "[startsWith(parameters('resourceName'), 'svc-')]" +``` + +```bash +dsc config get --file startswith.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Resource naming check + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + hasSvcPrefix: true +messages: [] +hadErrors: false +``` + +### Example 2 - Conditional routing + +The following example shows using `startsWith()` with `if()` to categorize a +service by its name prefix. + +```yaml +# startswith.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + serviceName: + type: string + defaultValue: api-orders +resources: +- name: Service classification + type: Microsoft.DSC.Debug/Echo + properties: + output: + classification: "[if(startsWith(parameters('serviceName'), 'api-'), 'API Service', 'Other Service')]" +``` + +```bash +dsc config get --file startswith.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Service classification + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + classification: API Service +messages: [] +hadErrors: false +``` + +### Example 3 - Multi-prefix evaluation + +The following example evaluates multiple possible prefixes. + +```yaml +# startswith.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + name: + type: string + defaultValue: db-primary-01 +resources: +- name: Prefix grouping + type: Microsoft.DSC.Debug/Echo + properties: + output: + isDb: "[startsWith(parameters('name'), 'db-')]" + isApi: "[startsWith(parameters('name'), 'api-')]" + isCache: "[startsWith(parameters('name'), 'cache-')]" +``` + +```bash +dsc config get --file startswith.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Prefix grouping + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + isDb: true + isApi: false + isCache: false +messages: [] +hadErrors: false +``` + +## Parameters + +### string + +The input string to evaluate. + +```yaml +Type: string +Required: true +Position: 1 +``` + +### prefix + +The prefix string to test for. + +```yaml +Type: string +Required: true +Position: 2 +``` + +## Output + +The `startsWith()` function returns a boolean value indicating whether the +input string starts with the specified prefix. + +```yaml +Type: bool +``` + +## Related functions + +- [`endsWith()`][00] - Determines whether a string ends with a suffix +- [`concat()`][01] - Concatenates strings together +- [`if()`][02] - Returns values based on a condition +- [`string()`][03] - Converts values to strings + + +[00]: ./endsWith.md +[01]: ./concat.md +[02]: ./if.md +[03]: ./string.md diff --git a/docs/reference/schemas/config/functions/uniqueString.md b/docs/reference/schemas/config/functions/uniqueString.md new file mode 100644 index 000000000..c1340a0fd --- /dev/null +++ b/docs/reference/schemas/config/functions/uniqueString.md @@ -0,0 +1,197 @@ +--- +description: Reference for the 'uniqueString' DSC configuration document function +ms.date: 08/12/2025 +ms.topic: reference +title: uniqueString +--- + +# uniqueString + +## Synopsis + +Creates a deterministic lowercase Base32 string from one or more input strings. + +## Syntax + +```Syntax +uniqueString([, , ...]) +``` + +## Description + +The `uniqueString()` function produces a stable hash-based string from one or +more input strings. The inputs are concatenated with dash (`-`) separators then +hashed using MurmurHash64 and Base32-encoded (RFC 4648 lowercase, no padding). +The same inputs always produce the same output, making it useful for generating +repeatable names that satisfy length and character constraints. + +Because the output is a non-cryptographic hash, there's no direct reverse +operation, but it doesn't provide secrecy. If the possible inputs are +predictable (such as a small set of env, region, or service names), an attacker +can brute-force or dictionary-guess the original values by recomputing hashes. +Don't use `uniqueString()` for secrets or security decisions. Use it only for +stable, deterministic naming. + +## Examples + +### Example 1 - Generate a name from components + +The following example generates a unique, deterministic identifier from a set +of input properties. + +```yaml +# uniquestring.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + env: + type: string + defaultValue: prod + service: + type: string + defaultValue: billing + region: + type: string + defaultValue: westus +resources: +- name: Deterministic name + type: Microsoft.DSC.Debug/Echo + properties: + output: + name: "[uniqueString(parameters('env'), parameters('service'), parameters('region'))]" +``` + +```bash +dsc config get --file uniquestring.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Deterministic name + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + name: f5saooq7aoueg +messages: [] +hadErrors: false +``` + +### Example 2 - Stable bucket partition keys + +The following example shows using `uniqueString()` to build a stable partition +key for storage or grouping. + +```yaml +# uniquestring.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + tenantId: + type: string + defaultValue: tenantA + dataType: + type: string + defaultValue: metrics +resources: +- name: Partition key generation + type: Microsoft.DSC.Debug/Echo + properties: + output: + partitionKey: "[uniqueString(parameters('tenantId'), parameters('dataType'))]" +``` + +```bash +dsc config get --file uniquestring.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Partition key generation + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + partitionKey: i5w466eimgg52 +messages: [] +hadErrors: false +``` + +### Example 3 - Compose with other functions + +The following example builds a prefixed resource identifier combining a literal +prefix and the hash output. + +```yaml +# uniquestring.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + project: + type: string + defaultValue: analytics + zone: + type: string + defaultValue: eu-central +resources: +- name: Prefixed identifier + type: Microsoft.DSC.Debug/Echo + properties: + output: + resourceId: "[concat('res-', uniqueString(parameters('project'), parameters('zone')))]" +``` + +```bash +dsc config get --file uniquestring.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Prefixed identifier + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + resourceId: res-ce56slj5eites +messages: [] +hadErrors: false +``` + +## Parameters + +### value1 + +The first string value to include in the hash input sequence. + +```yaml +Type: string +Required: true +Position: 1 +``` + +### value2, ... (additional values) + +Optional additional string values to include. Each is appended with a dash +separator before hashing. Argument order affects the result. + +```yaml +Type: string +Required: false +Position: 2+ +``` + +## Output + +The `uniqueString()` function returns a deterministic lowercase Base32 string. + +```yaml +Type: string +``` + +## Related functions + +- [`concat()`][00] - Concatenates strings together +- [`string()`][01] - Converts values to strings +- [`utcNow()`][02] - Returns the current UTC timestamp + + +[00]: ./concat.md +[01]: ./string.md +[02]: ./utcNow.md diff --git a/docs/reference/schemas/config/functions/utcNow.md b/docs/reference/schemas/config/functions/utcNow.md new file mode 100644 index 000000000..1da6b810d --- /dev/null +++ b/docs/reference/schemas/config/functions/utcNow.md @@ -0,0 +1,173 @@ +--- +description: Reference for the 'utcNow' DSC configuration document function +ms.date: 08/12/2025 +ms.topic: reference +title: utcNow +--- + +# utcNow + +## Synopsis + +Returns the current UTC timestamp when used as a parameter default. + +## Syntax + +```Syntax +utcNow() +utcNow() +``` + +## Description + +The `utcNow()` function returns the current time in UTC. It can only be used +when defining the `defaultValue` of a parameter in a configuration document. +Using it elsewhere produces an error. When called without arguments, it returns +an ISO 8601 timestamp with microsecond precision. When a format string is +provided, the output uses that custom format. + +The format string uses a subset of .NET date/time format patterns that DSC +internally maps to its formatting system. Unsupported tokens are passed +through literally. + +## Examples + +### Example 1 - Parameter default timestamp + +The following example assigns the current UTC time as a default parameter +value, then echoes it. + +```yaml +# utcnow.example.1.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + generatedAt: + type: string + defaultValue: "[utcNow()]" +resources: +- name: Show timestamp + type: Microsoft.DSC.Debug/Echo + properties: + output: + generatedAt: "[parameters('generatedAt')]" +``` + +```bash +dsc config get --file utcnow.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Show timestamp + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + generatedAt: 2025-08-12T14:23:05.123456Z +messages: [] +hadErrors: false +``` + +### Example 2 - Custom formatted timestamp + +The following example uses a custom format string to produce a friendly date +stamp. The format maps .NET patterns (`yyyy-MM-dd HH:mm:ss`) to the internal +formatter. + +```yaml +# utcnow.example.2.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + buildStamp: + type: string + defaultValue: "[utcNow('yyyy-MM-dd HH:mm:ss')]" +resources: +- name: Build metadata + type: Microsoft.DSC.Debug/Echo + properties: + output: + buildStamp: "[parameters('buildStamp')]" +``` + +```bash +dsc config get --file utcnow.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Build metadata + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + buildStamp: 2025-08-12 14:23:05 +messages: [] +hadErrors: false +``` + +### Example 3 - Combine with other functions + +The following example combines `utcNow()` with `concat()` and `string()` to +build an identifier that contains a timestamp. + +```yaml +# utcnow.example.3.dsc.config.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + timestamp: + type: string + defaultValue: "[utcNow('yyyyMMdd-HHmmss')]" +resources: +- name: ID generator + type: Microsoft.DSC.Debug/Echo + properties: + output: + releaseId: "[concat('release-', parameters('timestamp'))]" +``` + +```bash +dsc config get --file utcnow.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: ID generator + type: Microsoft.DSC.Debug/Echo + result: + actualState: + output: + releaseId: release-20250812-142305 +messages: [] +hadErrors: false +``` + +## Parameters + +### format + +An optional date/time format string using .NET-style tokens. If omitted, the +function returns an ISO 8601 UTC timestamp with microsecond precision. + +```yaml +Type: string +Required: false +``` + +## Output + +The `utcNow()` function returns the current UTC timestamp as a string. + +```yaml +Type: string +``` + +## Related functions + +- [`string()`][00] - Converts values to strings +- [`concat()`][01] - Concatenates strings together +- [`uniqueString()`][02] - Produces a deterministic hash-based string + + +[00]: ./string.md +[01]: ./concat.md +[02]: ./uniqueString.md