Azure-pipelines-tasks: Add more detail to commands.md documentation

[leftler]

The documentation located at https://github.com/Microsoft/vsts-tasks/blob/master/docs/authoring/commands.md needs more detail added to it, here are some things that I am still unsure of after trying to puzzle it out for a while

All the issues I have found mainly have been with the documentation of ##vso[task.logdetail]

• Does parentid need to be passed with every request or is it a write once field like name or order?
• What format should time be in for starttime and finishtime? If it is a format without timezone should it be local time or UTC?
• What format should the GUIDs be in?
• What should we be putting in for type? The two examples that you show use build as the value passed in, should we always pass in build or are there other valid values?
• What format does progress need to be in, can it accept decimals, can it accept commas?
• Is there well defined behavior when two objects have the same value for order?
• Examples are not actual examples: ##vso[task.logdetail id=new guid;name=project1;type=build;order=1]create new timeline record. would fail because id=new guid is not a valid value.

[leftler]

Also, it is not clear where "current operation" is used, or how doing parent id's provides any benefit. Neither is visible.

For example in the below image "G7x Build" is the parent of all other items in the list, It was constructed with

##vso[task.logdetail id={b07f2884-d4c5-4aaa-8a17-e20b44d31bee};type=build;name=G7x Build;order=1]

Then later commands like

##vso[task.logdetail id={8a8aa49e-9c3f-47bd-b58f-9c968e5cf760};parentid={b07f2884-d4c5-4aaa-8a17-e20b44d31bee};type=build;name=AppVer.vbp;order=1;state=Initialized]
##vso[task.logdetail id={dc21891a-42d1-4c2a-b36d-ad684709082d};parentid={b07f2884-d4c5-4aaa-8a17-e20b44d31bee};type=build;name=CostDisplayFormat.vbp;order=2;state=Initialized]
##vso[task.logdetail id={bc3649cc-0496-46cb-961e-d77f23fa98eb};parentid={b07f2884-d4c5-4aaa-8a17-e20b44d31bee};type=build;name=Desktop.vbp;order=3;state=Initialized]

are done. Then the main status is updated

##vso[task.logdetail id={b07f2884-d4c5-4aaa-8a17-e20b44d31bee}]Handle SelectProjects

However there is 0 indication of any kind of hierarchy nor those status updates on the Web UI nor in the logs associated with the build. The only place I could see Handle SeclectedProjects was in the console window running the agent on the build machine (and even then it did not include then name, it just wrote : Handle SelectProjects unlike the AppVer.vbp: Starting that gets generated when I first mark a object initialized which includes the detail name).

[bgever]

I'm also struggling with the documentation. Can I use the type parameter to log Test results? Is test a valid record type? I'd like to write a reporter for Mocha test progress.

[Kujawadl]

Can we get an update on this? I can't find any other documentation on these commands.

I can't get anything using task.logdetail working...

[logicbomb421]

I too would like an update here. There appear to be a lot of useful vso commands we can utilize, but as the OP stated, the documentation is really lacking. The few commands I currently utilize I got working via trial and error.

[redshiftz]

What is the status of this?

[matthid]

Yes I agree this needs to added to the docs. For now you can peek into the code and answer some of the questions:

https://github.com/Microsoft/vsts-agent/blob/59b25208aa1c17a30c1dddc4828044fd89513599/src/Agent.Worker/TaskCommandExtension.cs#L84-L237

Does parentid need to be passed with every request or is it a write once field like name or order?

No it can be left out. If it is given it needs to be equal to the first usage.

What format should time be in for starttime and finishtime? If it is a format without timezone should it be local time or UTC?

DateTime.TryParse(dateTimeText, CultureInfo.CurrentCulture, DateTimeStyles.AdjustToUniversal, out dateTime) is used:

https://github.com/Microsoft/vsts-agent/blob/59b25208aa1c17a30c1dddc4828044fd89513599/src/Agent.Worker/TaskCommandExtension.cs#L611-L620

What format should the GUIDs be in?

new Guid(...) is used.

What should we be putting in for type? The two examples that you show use build as the value passed in, should we always pass in build or are there other valid values?

It looks like a custom string.

What format does progress need to be in, can it accept decimals, can it accept commas?

Int32.TryParse(percentCompleteValue, out progress) is used.

[d3r3kk]

I don't see any sort of sub-timeline information anywhere in the latest version of the Build output UX.

In the newest UX for builds, where does the output of logdetail go? Is this even relevant information any longer?

[LeMaciek]

I was hoping it will be improved in new Azure Devops server 2019, but it seems like it was removed. I don't see any timeline view... Command ##vso[task.logdetail is basically useless and should be removed from the documenation...

[tillig]

I just ran into this myself, wanting to provide some detail about the state of some long running tasks.

It appears this issue noted that when the build log display changed, the timeline with this info disappeared. The author of the issue was directed to take it up with the Developer Community website which isn't great as far as explaining _why_ this doesn't work as expected... or really what to expect.

Effectively the same question has been asked on the docs repo to see if the docs could add clarification around what the expected outcome of task.logdetail usage is... but again, the author was punted to ask on StackOverflow or the Developer Community website.

The only answered StackOverflow question I can find is here, which basically says this isn't available in the "new build output." There's a nearly identical answer on this question which wasn't accepted.

In all of these cases, the "answer" seems to be "someone should suggest that get implemented," but I think it's valid to have - somewhere in the documentation - that with the "new build output" view _the timeline is no longer a thing that should be expected._ Whether it should be re-implemented, sure, may be something that should be voted on, but man, it'd be nice to know that it's not just me unable to find where my cheese was moved.

[tillig]

As a follow up, apparently this was suggested on the Developer Community site and was closed due to 90 days of inactivity. It was reported a second time and summarily closed with the Microsoft representative pretty clearly not understanding what was being asked.

I'm not sure how we might be expected to make any traction on getting docs updated or getting the view fixed when it doesn't seem anyone's actually listening to the issue.

[github-actions[bot]]

This issue is stale because it has been open for 180 days with no activity. Remove the stale label or comment on the issue otherwise this will be closed in 5 days

[chwarr]

This issue still exists as more-or-less as originally reported. It should not be marked as stale. The next action needs to be taken by the Azure Pipelines Task team to clarify the format and semantics here. This is not something that we, the users of Azure Pipelines, can definitively answer ourselves.