Skip to content

Commit eb30928

Browse files
erdembayarerdembayar
committed
Add more complex scenarios.
1 parent c1def2b commit eb30928

File tree

1 file changed

+143
-10
lines changed

1 file changed

+143
-10
lines changed

‎proposed/2021/MachineReadableOutput.md‎

Lines changed: 143 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ Project 'MyProjectB' has the following package references
7575
```json
7676
{
7777
"version": 1,
78+
"parameters": "",
7879
"projects": {
7980
"MyProjectA": [
8081
{
@@ -169,6 +170,7 @@ Project `MyProjectB` has the following updates to its packages
169170
```json
170171
{
171172
"version": 1,
173+
"parameters": "--outdated",
172174
"sources": [
173175
"https://api.nuget.org/v3/index.json",
174176
"https://apidev.nugettest.org/v3-index/index.json"
@@ -270,6 +272,7 @@ Project `MyProjectB` has the following deprecated packages
270272
```json
271273
{
272274
"version": 1,
275+
"parameters": "--deprecated",
273276
"sources": [
274277
"https://api.nuget.org/v3/index.json",
275278
"https://apidev.nugettest.org/v3-index/index.json"
@@ -379,6 +382,7 @@ Project `MyProjectB` has the following vulnerable packages
379382
```json
380383
{
381384
"version": 1,
385+
"parameters": "--vulnerable",
382386
"sources": [
383387
"https://api.nuget.org/v3/index.json",
384388
"https://apidev.nugettest.org/v3-index/index.json"
@@ -505,6 +509,7 @@ Project 'MyProjectB' has the following package references
505509
```json
506510
{
507511
"version": 1,
512+
"parameters": "--include-transitive",
508513
"projects": {
509514
"MyProjectA": [
510515
{
@@ -600,6 +605,128 @@ Project 'MyProjectB' has the following package references
600605
}
601606
```
602607

608+
609+
#### `> dotnet list package --include-transitive --outdated --framework net5.0`
610+
611+
The following sources were used:
612+
https://api.nuget.org/v3/index.json
613+
https://apidev.nugettest.org/v3-index/index.json
614+
615+
No packages were found for the project `MyProjectA` given the specified frameworks.
616+
Project `MyProjectB` has the following updates to its packages
617+
[net5.0]:
618+
Top-level Package Requested Resolved Latest
619+
> NuGet.Commands 4.8.0-preview3.5278 4.8.0-preview3.5278 6.0.0
620+
> Text2Xml.Lib 1.1.2 1.1.2 1.1.4
621+
622+
Transitive Package Resolved Latest
623+
> Microsoft.CSharp 4.0.1 4.7.0
624+
> Microsoft.NETCore.Platforms 1.1.0 6.0.1
625+
> Microsoft.NETCore.Targets 1.1.0 5.0.0
626+
627+
#### `> dotnet list package --include-transitive --outdated --framework net5.0 --format json`
628+
629+
```json
630+
{
631+
"version": 1,
632+
"parameters": "-include-transitive --outdated --framework net5.0",
633+
"sources": [
634+
"https://api.nuget.org/v3/index.json",
635+
"https://apidev.nugettest.org/v3-index/index.json"
636+
],
637+
"projects": {
638+
"MyProjectA": [
639+
],
640+
"MyProjectB": [
641+
{
642+
"Path": "src/lib/MyProjectB.csproj",
643+
"framework": "net5.0",
644+
"topLevelPackages": [
645+
{
646+
"id": "NuGet.Commands",
647+
"requestedVersion": "4.8.0-preview3.5278",
648+
"resolvedVersion": "4.8.0-preview3.5278",
649+
"latestVersion": "6.0.0",
650+
},
651+
{
652+
"id": "Text2Xml.Lib",
653+
"requestedVersion": "1.1.2",
654+
"resolvedVersion": "1.1.2",
655+
"latestVersion": "1.1.4",
656+
}
657+
],
658+
"transitivePackages": [
659+
{
660+
"id": "Microsoft.CSharp",
661+
"resolvedVersion": "4.0.1",
662+
"latestVersion": "4.7.0",
663+
}
664+
...
665+
]
666+
}
667+
]
668+
}
669+
}
670+
```
671+
672+
#### `> dotnet list package --include-transitive --deprecated --framework net5.0`
673+
674+
The following sources were used:
675+
https://api.nuget.org/v3/index.json
676+
https://apidev.nugettest.org/v3-index/index.json
677+
678+
No packages were found for the project `MyProjectA` given the specified frameworks.
679+
Project `MyProjectB` has the following deprecated packages
680+
[net5.0]:
681+
Top-level Package Requested Resolved Reason(s) Alternative
682+
> NuGet.Core 2.13.0 2.13.0 Legacy
683+
684+
Transitive Package Resolved Reason(s) Alternative
685+
> NuGet.Packaging.Core 4.8.0-preview3.5278 Legacy NuGet.Packaging >= 0.0.0
686+
687+
#### `> dotnet list package --include-transitive --deprecated --framework net5.0 --format json`
688+
689+
```json
690+
{
691+
"version": 1,
692+
"parameters": "--include-transitive --deprecated --framework net5.0",
693+
"sources": [
694+
"https://api.nuget.org/v3/index.json",
695+
"https://apidev.nugettest.org/v3-index/index.json"
696+
],
697+
"projects": {
698+
"MyProjectA": [
699+
],
700+
"MyProjectB": [
701+
{
702+
"Path": "src/lib/MyProjectB.csproj",
703+
"framework": "net5.0",
704+
"topLevelPackages": [
705+
{
706+
"id": "NuGet.Core",
707+
"requestedVersion": "2.13.0",
708+
"resolvedVersion": "2.13.0",
709+
"deprecationReasons": ["Legacy"]
710+
}
711+
],
712+
"transitivePackages": [
713+
{
714+
"id": "Microsoft.CSharp",
715+
"resolvedVersion": "4.0.1",
716+
"deprecationReasons": ["Legacy"],
717+
"alternativePackage": {
718+
"id": "NuGet.Packaging",
719+
"versionRange": "[0.0.0,)"
720+
}
721+
}
722+
...
723+
]
724+
}
725+
]
726+
}
727+
}
728+
```
729+
603730
## Compatibility
604731

605732
We start with `version 1`, as long as we don't remove or rename then it'll be backward compatible. In case [we change version](https://stackoverflow.com/a/13945074) just add new properties, keep old ones even it's not used.
@@ -628,32 +755,38 @@ Please note, except "tab completion" (for dotnet) part all changes would be insi
628755

629756
* https://docs.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-counters One idea we can take from `dotnet counter` is we can specify output file with `-o`, `--output` option. So instead of writing output into console, it allows output directly saved into file. It allows both `csv` and `json` formats, currently saved file doesn't have version concept.
630757

758+
* https://github.com/NuGet/Home/wiki/Enable-repeatable-package-restore-using-lock-file It's very similar what we're doing here, and it has schema versioning. [sample](https://gist.github.com/erdembayar/4894b66bde227147b60e60997d20df41) Only major difference is json object are grouped under TFM unlike `dotnet list package` where items are grouped under projects. Below are possible takeaways.
759+
* Direct/top level packages point to dependency packages. >> Could be included, down side is duplicate information, increase json size. Also I feel https://github.com/NuGet/Home/issues/11553 addresses this issue better, because in the end who transitive dependency brought in is more important than what dependencies exist under each top package.
760+
* Content hash. >> It's very easy to include it, question is how about source? Related issue https://github.com/NuGet/Home/issues/11552
761+
631762
## Unresolved Questions
632763

633764
* Donnie: When I want to create archival records, will I want something more unique than the project name?
634765
Adding the path, repo, commit ID, etc seems complex. [r766920783](https://github.com/NuGet/Home/pull/11446#discussion_r766920783)
635-
* `name/relative path to solution` could be solution here.
766+
>> `path property` could be solution here, see proposal.
636767
637768
* Donnie: How can we record in the output that --include-transitive wasn't used here?
638769
In other words, if I look at this output years from now, how would I know whether any transitives were in this project? [r766924390](https://github.com/NuGet/Home/pull/11446#discussion_r766924390)
639-
* packages.lock.json format could be used here.
770+
>> We could include options and parameters used here.
640771
641772
* Loïc : How would this format evolve if we add another "package pivot" in addition to top level and transitive packages? For example, what if we add new package kinds for source generators, Roslyn analyzers, etc...? [r767026799](https://github.com/NuGet/Home/pull/11446#discussion_r767026799)
642773

643774
>> Out of scope from MVP, this schema can evolve over time, by the time we have necessity to do change we can make more educated decision.
644775
645-
* Could we use existing packages.lock.json format? [sample](https://gist.github.com/erdembayar/4894b66bde227147b60e60997d20df41)
646-
* Direct/top level packages point to dependency packages.
647-
* Content hash. >> out of scope for now. Tracking issue https://github.com/NuGet/Home/issues/11552
648-
649776
## Future Possibilities
650777

778+
If we address them in plain `dotnet list package` then we'll address in `json output` too.
779+
780+
* Include source info for all options. https://github.com/NuGet/Home/issues/11556
781+
782+
* Include hash + source for package, because same package ID+version might have different hash. It can be used to detect [dependency confusion attack](https://github.com/NuGet/Home/pull/11446#discussion_r767030495), tracking issue: https://github.com/NuGet/Home/issues/11552
783+
784+
* Include hash for each package, sub issue of above.
785+
651786
* Show resolution tree for transitive dependencies and constraint for dependency [resolved version](https://github.com/NuGet/Home/pull/11446/files#r777233006), tracking issue: https://github.com/NuGet/Home/issues/11553
652787

653-
* Return different exit codes if any vulnerabilities, deprecations, outdated package is [detected](https://github.com/NuGet/Home/blob/dotnet-audit/proposed/2021/DotNetAudit.md#dotnet-audit-exit-codes).
788+
* Include-transitive dependencies by default [r766924390](https://github.com/NuGet/Home/pull/11446#discussion_r766924390), workaround pass `--include-transitive`, tracking issue https://github.com/NuGet/Home/issues/11550
654789

655790
* `--all` option for dotnet list package [r766860629](https://github.com/NuGet/Home/pull/11446#discussion_r766860629), tracking issue https://github.com/NuGet/Home/issues/11551
656791

657-
* Include-transitive dependencies by default [r766924390](https://github.com/NuGet/Home/pull/11446#discussion_r766924390), tracking issue https://github.com/NuGet/Home/issues/11550
658-
659-
* Include hash + source for package, because same package ID+version might have different hash. It can be used to detect [dependency confusion attack](https://github.com/NuGet/Home/pull/11446#discussion_r767030495), tracking issue: https://github.com/NuGet/Home/issues/11552
792+
* Return different exit codes if any vulnerabilities, deprecations, outdated package is [detected](https://github.com/NuGet/Home/blob/dotnet-audit/proposed/2021/DotNetAudit.md#dotnet-audit-exit-codes).

0 commit comments

Comments
 (0)