Exposing project information to tools

[karolz-ms]

Tools like Visual Studio might need to read some information that is stored in azure.yaml. For example, the user might indicate that they want to "deploy" a particular C# project from Visual Studio Solution Explorer. For that Visual Studio needs to know what is the AZD "service name" that corresponds to the C# project, so that it can invoke the azd deploy --service xxx command correctly.

There are a few ways we could go about making it happen

1. Just have the tools read azure.yaml directly.
   We have a schema for the file and libraries are available. That said, the format of azure.yaml file will probably be evolving, and making sure tools follow the changes is a challenge. The magnitude of the challenge is somewhat hard to predict.

2. Develop and publish libraries to read/write project information in azure.yaml file.
   This would allow AZD team to make changes to the file schema while isolating the consumers from most of them (or, for more substantial changes, at least the consumers would get a decent parsing error message and have a chance to upgrade to a new library version). This does represent additional work though, including the logistics of publishing libraries etc.

3. Add new CLI command(s) for exposing project information in machine-readable format (JSON)
   This option would isolate tools from minor changes to azure.yaml file format, similar to option 2, but would probably be insufficient for major changes. It would also mean adding commands that very few users would benefit from.

Thoughts?

[abpiskunov]

I like the special command that could emit some tooling info, that command might be not public and be there for tools to call it etc ...

[karolz-ms]

Tell us more why you like this option please

[abpiskunov]

In case of assembly we are not really solving compatibility issues since if tooling uses old assembly and format changed it would fail (Also tool would have to load extra assembly in memory which we try to minimize). Same thing for tooling reading the file itself.

Having tool command hides all schema behind and only returns metadata that tools expect.

Having tool read file might work only when there are some guarantees that format would never change but only extended, i.e. new content would be added, but old would not change.

[karolz-ms]

Let's say we would introduce azd project family of commands. What sub-commands would you like to see and what information would they return? E.g. consider azd project list-services command.

[vijayrkn]

Are we thinking of a name-value pair(s) as the return to these commands that maps the source to the target?

[abpiskunov]

yes by default and also accept --json parameter for tools to parse it in json format

[karolz-ms]

@abpiskunov @vijayrkn it would be very helpful if you provided some examples of that mapping might look like.

E.g. given the app that has this specific structure (number/type of application services plus number/type of supporting cloud services/dependencies), these are the "questions" (azd CLI invocations) that VS would ask, and this is the JSON data that VS is expected to receive.

[vijayrkn]

I think we may need to add the type of the host as well when we support - Functions, ACA etc... The type could be the RP name to avoid confusion.

[
    {
        "name": "api",
        "projectPath": "src/api/Api.csproj", <- for dotnet projects include file name that azd would pick when some action happens
        "host": "appservice1",
        "hostType": "AppService"    
    },
    {
        "name": "web",
        "projectPath": "src/web", <- for non .Net projects it is fine not to have project file here
        "host": "appservice2",
        "hostType": "AppService"
    },
    {
        "name": "serverless",
        "projectPath": "src/serverless", <- for non .Net projects it is fine not to have project file here
        "host": "functionapp5",
        "hostType": "AzureFunction"
    }
]

[ellismg]

@vijayrkn - Just wondering - how do you plan to use the hostType/host? I am wondering - would it make sense for us to instead just expose the id of the resource that deploy would target? That would contain the RP as part of the resource ID and also would save anyone the work of having to compute the target themselves.

BTW - In the above example (with both host and hostType) - I don't understand what the host is now - Is it just the name of the target resource?

[abpiskunov]

host there is a resource name and host type resource type. Yes, full resourceId would also work, we can parse it already on our end. What ever is easier for you and consistent with other sub commands. In above example we picked those properties since they already were in azure.yaml.

[vijayrkn]

Should we just call it reasourceId in that case?

    {
        "name": "serverless",
        "projectPath": "src/serverless", <- for non .Net projects it is fine not to have project file here
        "resourceId": "<full resource id>",
    }

[ellismg]

I think resourceId makes sense. Interested in how you plan to use this? I assume that you'd still use azd to do the actual deployment. What would this light up in VS?

A reason I ask this question - we are starting to look at Kubernetes (and specifically AKS support) and I'm less certain that resource id makes sense there (since the target of any deployment is probably going to be some service object inside your Kubernetes cluster) so I want to better understand how this information plans to be used.

Additionally, we may not always have the resource id of the thing we are going to deploy to (consider the case where you initialize a new project but have not yet run azd provision to create the azure resources that back it), so this field may not always be set in our return value. Is that going to cause issues?

[rajeshkamal5050]

@abpiskunov @vijayrkn

Team @jongio @savannahostrowski @karolz-ms @ellismg had a discussion on this and decided to,

• Add a new internal CLI command to expose the environment, project information to VS.
• More details on the actual CLI command and its i/o will be shared soon. @ellismg will take a stab at it and provide details for the same after an internal review.

[philliphoff]

A minor nit: while I like the approach, I would shy away from referring to them as "internal" commands. While it's fine to not emphasize commands intended for consumption by other tooling relative to those invoked by actual users, they still need to be reasonably generic and publicly documented for the benefit of all tooling, VS and otherwise. (I fully expect that to be the case anyway, but just cringe a bit at the term.)

[ellismg]

I started the ball rolling on the work to expose azd show here: #616.