https://github.com/devlooped/json
JsonPeek and JsonPoke tasks implementations
https://github.com/devlooped/json
dotnet json msbuild
Last synced: about 1 year ago
JSON representation
JsonPeek and JsonPoke tasks implementations
- Host: GitHub
- URL: https://github.com/devlooped/json
- Owner: devlooped
- License: mit
- Created: 2021-09-13T18:10:00.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-03-18T00:12:44.000Z (about 1 year ago)
- Last Synced: 2025-03-25T03:34:06.912Z (about 1 year ago)
- Topics: dotnet, json, msbuild
- Language: C#
- Homepage: https://clarius.org/json
- Size: 196 KB
- Stars: 8
- Watchers: 1
- Forks: 1
- Open Issues: 8
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- Funding: .github/FUNDING.yml
- License: license.txt
Awesome Lists containing this project
README
 JsonPeek and JsonPoke MSBuild Tasks
============
[](https://github.com/devlooped/json/blob/main/license.txt)
[](https://github.com/devlooped/json/actions)
 JsonPeek
============
[](https://www.nuget.org/packages/JsonPeek)
[](https://www.nuget.org/packages/JsonPeek)
Read values from JSON using JSONPath.
Usage:
```xml
```
Parameters:
| Parameter | Description |
| ----------- | -------------------------------------------------------------------------------------------------------------- |
| Content | Optional `string` parameter.
Specifies the JSON input as a string. |
| ContentPath | Optional `ITaskItem` parameter.
Specifies the JSON input as a file path. |
| Empty | Optional `string` parameter.
Value to use as a replacement for empty values matched in JSON. |
| Query | Required `string` parameter.
Specifies the [JSONPath](https://goessner.net/articles/JsonPath/) expression. |
| Result | Output `ITaskItem[]` parameter.
Contains the results that are returned by the task. |
You can either provide the path to a JSON file via `ContentPath` or
provide the straight JSON content to `Content`. The `Query` is a
[JSONPath](https://goessner.net/articles/JsonPath/) expression that is evaluated
and returned via the `Result` task parameter. You can assign the resulting
value to either a property (i.e. for a single value) or an item name (i.e.
for multiple results).
JSON object properties are automatically projected as item metadata when
assigning the resulting value to an item. For example, given the following JSON:
```JSON
{
"http": {
"host": "localhost",
"port": 80,
"ssl": true
}
}
```
You can read the entire `http` value as an item with each property as a metadata
value with:
```xml
```
The `Http` item will have the following values (if it were declared in MSBuild):
```xml
localhost
80
true
```
These item metadata values could be read as MSBuild properties as follows, for example:
```xml
@(Http -> '%(host)')
@(Http -> '%(port)')
@(Http -> '%(ssl)')
```
In addition to the explicitly opted in object properties, the entire node is available
as raw JSON via the special `_` (single underscore) metadata item.
If the matched value is empty, no items (because items cannot be constructed with empty
identity) or property value will be returned. This makes it difficult to distinguish a
successfully matched empty value from no value matched at all. For these cases, it's
possible to specify an `Empty` value to stand-in for an empty (but successful) matched
result instead, which allow to distinguish both scenarios:
```xml
```
 JsonPoke
============
[](https://www.nuget.org/packages/JsonPoke)
[](https://www.nuget.org/packages/JsonPoke)
Write values to JSON nodes selected with JSONPath
Usage:
```xml
```
Parameters:
| Parameter | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content | Optional `string` input/output parameter.
Specifies the JSON input as a string and contains the updated
JSON after successful task execution. |
| ContentPath | Optional `ITaskItem` parameter.
Specifies the JSON input as a file path. |
| Query | Required `string` parameter.
Specifies the [JSONPath](https://goessner.net/articles/JsonPath/) expression. |
| Value | Optional `ITaskItem[]` parameter.
Specifies the value(s) to be inserted into the specified path. |
| RawValue | Optional `string` parameter.
Specifies the raw (JSON) value to be inserted into the specified path. |
You must either provide the path to a JSON file via `ContentPath` or
raw JSON content via `Content`.
The `Value` can be an item group, and in that case, it will be inserted into the
JSON node matching the [JSONPath](https://goessner.net/articles/JsonPath/) expression
`Query` as an array. `RawValue` can be used to provide
an entire JSON fragment as a string, with no conversion to an MSBuild item at all.
The existing JSON node will determine the data type of the value being written,
so as to preserve the original document. Numbers, booleans and DateTimes are
properly parsed before serializing to the node.
```xml
{
"http": {
"host": "localhost",
"port": 80,
"ssl": true
}
}
```
Note how we update multiple values and assign the updated content to the
same `$(Json)` property so it can be used in subsequent updates. The last
`Message` task will render the following JSON:
```JSON
{
"http": {
"host": "example.com",
"port": 80,
"ssl": true
}
}
```
> NOTE: The port number was preserved as a number, as is the `ssl` boolean.
To force a value to be interpreted as a string, you can surround it with double or single quotes.
For example, given the following JSON file:
```JSON
{
"http": {
"ports": [
"80"
]
}
}
```
We can replace the `ports` array with string values as follows (without the
explicit quotes, the values would be interpreted as numbers otherwise):
```xml
```
Result:
```JSON
{
"http": {
"ports": [
"8080",
"1080"
]
}
}
```
It's also possible to write a complex object based on MSBuild item metadata:
```xml
localhost
80
true
```
Result:
```JSON
{
"http": {
"host": "localhost",
"port": 80,
"ssl": true
}
}
```
Note how the native JSON type was automatically inferred, even though everything is
basically a string in MSBuild. As noted above, you can surround any of the item metadata
values in double or single quotes to force them to be written as strings instead.
The task can create entire object hierarchies if any segment of the path expression is
not found, which makes it very easy to create complex structures by assigning a single
value. For example, if the `http` section in the examples above didn't exist at all,
the following task would add it automatically, prior to assigning the `ssl` property to `true`:
```xml
```
This also works for indexed queries, such as adding launch profile to
[launchSettings.json](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/environments?view=aspnetcore-6.0#lsj)
by simply assigning a value:
```xml
```
which would create the following entry:
```json
{
"profiles": {
"IIS Express": {
"commandName": "IISExpress",
}
}
}
```
Array index is also supported as part of the query, to modify existing values. If the array is empty
or non-existent, it's also possible to just use the index `[0]` to denote the new node should be the
sole element in the new array, like for adding a new watch file value to
[host.json](https://docs.microsoft.com/en-us/azure/azure-functions/functions-host-json):
```xml
```
Which results in:
```json
{
...
"watchFiles": [ "myFile.txt" ]
}
```
It's quite common to want to add entries to an existing array, usually at the end of the array. The
JSONPath syntax supports indexes that start from the end of the array (such as `[-1:]`), but if the
array had any values already, that would match whichever is the last element, meaning in an *update*
to that element's value. Since we need a different syntax for *inserting* a new node, starting from
the end of the list, we leverage the C# syntax `^n` where `n` is the position starting from the end.
To add a new element at the end of the list, the index `[^1]` can be used. `^2` means prior to last
and so on.
For example, to *add* a new watched file to the array in the example above, we could use:
```xml
```
Given an existing `host.json` file like the one above, we would get a new file added like so:
```json
{
...
"watchFiles": [ "myFile.txt", "myOtherFile.txt" ]
}
```
If the `watchFiles` property didn't exit at all or had no elements, the result would be
the same as if we used `[0]`, but this makes the code more flexible if needed.
The modified JSON nodes can be assigned to an item name using the `Result` task property,
and will contain the item path (matching the `Query` plus the index if multiple nodes were modified)
as well as the `Value` item metadata containing the raw JSON that was written.
# Dogfooding
[](https://pkg.kzu.io/index.json)
[](https://github.com/devlooped/json/actions)
We also produce CI packages from branches and pull requests so you can dogfood builds as quickly as they are produced.
The CI feed is `https://pkg.kzu.io/index.json`.
The versioning scheme for packages is:
- PR builds: *42.42.42-pr*`[NUMBER]`
- Branch builds: *42.42.42-*`[BRANCH]`.`[COMMITS]`
# Sponsors
[](https://github.com/clarius)
[](https://github.com/KirillOsenkov)
[](https://github.com/MFB-Technologies-Inc)
[](https://github.com/decriptor)
[](https://github.com/torutek-gh)
[](https://github.com/drivenet)
[](https://github.com/AshleyMedway)
[](https://github.com/Keflon)
[](https://github.com/tbolon)
[](https://github.com/kfrancis)
[](https://github.com/twenzel)
[](https://github.com/Giorgi)
[](https://github.com/unoplatform)
[](https://github.com/dansiegel)
[](https://github.com/rbnswartz)
[](https://github.com/jfoshee)
[](https://github.com/Mrxx99)
[](https://github.com/eajhnsn1)
[](https://github.com/IxTechnologies)
[](https://github.com/davidjenni)
[](https://github.com/Jonathan-Hickey)
[](https://github.com/okyrylchuk)
[](https://github.com/akunzai)
[](https://github.com/jakobt)
[](https://github.com/seanalexander)
[](https://github.com/tinohager)
[](https://github.com/ploeh)
[](https://github.com/KenBonny)
[](https://github.com/SimonCropp)
[](https://github.com/agileworks-eu)
[](https://github.com/sorahex)
[](https://github.com/arsdragonfly)
[](https://github.com/vezel-dev)
[](https://github.com/ChilliCream)
[](https://github.com/4OTC)
[](https://github.com/sponsors/devlooped)
[Learn more about GitHub Sponsors](https://github.com/sponsors)