Dockertools: Add documentation about launchSettings.json, .csproj options, Dockerfile requirements

[tillig]

When you right-click in the VS Solution Explorer and add Docker support to an ASP.NET Core project, it does a few things - you get a Dockerfile and you get a launchSettings.json entry, for example.

launchSettings.json ends up containing a bunch of things that aren't part of the launchSettings schema like httpPort, sslPort, and useSSL.

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "https://localhost:44308",
      "sslPort": 44308
    }
  },
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "profiles": {
    "IIS Express (Development)": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "launchUrl": "",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "Kestrel (Development)": {
      "commandName": "Project",
      "launchBrowser": true,
      "launchUrl": "",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "https://localhost:44308"
    },
    "Docker": {
      "commandName": "Docker",
      "launchBrowser": true,
      "launchUrl": "{Scheme}://{ServiceHost}:{ServicePort}/",
      "httpPort": 58260,
      "useSSL": false,
      "sslPort": 44308
    }
  }
}

There are also some magic strings in there - {Scheme}, for example. Other than the ones shown, are there others?

There things you can put in your .csproj file like <DockerDebuggeeArguments> that can affect how Docker starts up your container.

You can also add things like environmentVariables in launchSettings.json for the Docker configuration and those will get passed _to the application_ but won't be global environment variables you can inspect in the running container.

The Dockerfile that gets generated has a bunch of named intermediate containers but it turns out you only need the one named base for the VS debugging to work.

There have been other issues (eg #62, #160) that have touched on some of this, but... it'd be nice if there was documentation covering the options available in launchSettings.json, .csproj files, and so on. It's really hard to figure this stuff out and ends up being a manual trek through .props and .targets files, decompilers on the libraries installed with VS, and slogging through issues and forums.

[bwateratmsft]

Thanks @tillig. We agree on the need for documentation and are working on it.

[tillig]

In the meantime, I blogged a lot of the stuff I've found whilst spelunking, in case that helps anyone.

[bwateratmsft]

@tillig That guide is great! To address the mystery of how "dotnet" starts inside the container in debug mode--

1. We launch VSDBG using that long-ish "docker exec" script, /bin/sh -c "ID=.; if....". The reason for this long script is to figure out within the container if it's Alpine or Debian/Ubuntu, because we use a different version of VSDBG depending on which.
2. After VSDBG is launched, Visual Studio attaches to it and instructs it to launch the app itself, with "dotnet". It also passes in the environment variables from launchSettings.json. Having VSDBG launch the app means that you are attached to the process from the very beginning, and won't miss something going wrong in startup.

[tillig]

That explains why I didn't see it in Process Monitor, then. Thanks! I tried to get execsnoop and auditd running to see if I could catch when it was starting up but gave up. This helps!

[k-antonius]

Completely agree on the need for documentation. My team has been struggling with these issues.

[sgreenmsft]

To update this issue, general documentation for Visual Studio container tools is available here:
https://docs.microsoft.com/en-us/visualstudio/containers/?view=vs-2019

We've recently added a conceptual article covering how VS uses Dockerfiles: https://docs.microsoft.com/en-us/visualstudio/containers/container-build?view=vs-2019

And a reference table for MSBuild properties: https://docs.microsoft.com/en-us/visualstudio/containers/container-msbuild-properties?view=vs-2019

Additional documentation (e.g. launchSettings.json) is in the works. In the meantime, please let us know where the docs fall short and any struggles you have.

[tillig]

I updated my blog article to correct things I had wrong and point folks to the official docs to learn more. Thanks for continuing to improve this stuff!

[ghogen]

@tillig You can also contribute directly to the Container Tools docs by filing issues or PRs to https://github.com/MicrosoftDocs/visualstudio-docs - just hit the "Edit" button on any doc page to view the article's source in Markdown, and submit changes though GitHub.

[tillig]

It appears since this issue was filed this document on launchSettings.json was added, which is awesome. That was really the point of this particular issue, so we can probably call this closed.

As for docs that explain _exactly what's going on under the covers_, that may or may not be info for the MSDN site. That said, it seems the DockerTools aren't actually open source so we can't really keep the docs with the source on that lower level stuff.

I kind of had to reverse-engineer for my blog how the low level bits actually worked, so I'm not sure if I'm qualified to PR it to https://github.com/MicrosoftDocs/visualstudio-docs, but I can if it's interesting. Probably would be a new page rather than an add-on to the existing page.

[ghogen]

@tillig Yes, I added the launchSettings.json doc and I think at this point we've covered most of the details. But LMK if you have any ideas or suggestions for the docs.

[bwateratmsft]

As @tillig suggested I'll close this issue. Thanks @tillig for making such an awesome guide! And thanks @ghogen for the official docs!