Rename items (elements) used in service reference scenarios

[dougbu]

This is a pivot on what users see in their projects when using service reference features.

Current items are

<ServiceFileReference Include="SomeFile" ... />
<ServiceUriReference Include="https://SomeUri" ... />
<ServiceProjectReference Include="../SomeProject/SomeProject.csproj" ... />

New elements will be
<ProtobufReference Include="SomeFile" ... />

<OpenApiReference Include="SomeFile" ... />
<OpenApiProjectReference Include="../SomeProject/SomeProject.csproj" ... />

<OpenApiReference Include="SomeFile" SourceUri="https://SomeUri" ... />
<ProtobufReference Include="../SomeProject/SomeProject.csproj" ... />

<OpenApiProjectReference Include="../SomeProject/SomeProject.csproj" ... />

[dougbu]

Open questions:

1. Do we use the new item names when calling out to code generation partners? I lean toward "yes" for consistency but that adds more parts that need to change. @glennc do you want to make the call here?
2. Is the SourceUri case interesting for gRPC too? @shirhatti?
3. Is the <ProtobufReference Include="../SomeProject/SomeProject.csproj" ... /> case a bit too confusing? Naming (of the extracted document -- just in the Open API case, the C# files, and the the generated class) might be simpler and more consistent if this were something like <ProtobufReference Include="SomeFile" SourceProject="../SomeProject/SomeProject.csproj" ... />. @glennc?
4. We're leaning toward supporting the (Open API-only) case where the service project does not generate a document on disk when it builds. Will there be an explicit gesture to "refresh" the document a client project extracts? Or, will this be done automatically e.g. on every non-design-time build? @glennc and @mlorbetske I think both of you have opinions here…

[glennc]

We talked about how to handle the upgrade from preview3 to 4 with the new names. What we want is for it to fail hard and fast so that customers know straight away to go rename the element.

[glennc]

Answering open questions:

1. Yeah, consistency seems good and we have to update them anyway
2. This doesn't matter anymore due to the naming, we also cut URI support
3. The project case is just a wildacard for * references
4. Doesn't matter given the new split.

[dougbu]

From discussions today:

1. Make the Swagger / OpenAPI project case a true project reference to ensure build ordering
2. Add metadata to ensure client project doesn't get assemblies / types from the server project
3. Call a separate project on the web api project to get the actual file list the project wants to surface
   • do this for gRPC too but skip (1) and (2) for that case
   • or, skip project references for gRPC choice

Bottom line: Use what's there and build on it.

[dougbu]

<ProjectReference include = "..\someproject\someproject.csproj" ReferenceOutputAssembly="false" OpenApiReference="true"/>

<ItemGroup>
   <!-- Check in the IDE. Not clear what VS does with such a virtual element? -->
   <ProjectReference Include="@(OpenApiProjectReference)"
        ReferenceOutputAssembly="false"
        Exclude="@(ProjectReference)" OpenApiReference="true" />
</ItemGroup>
<!-- Disable in design-time builds? Definitely requires an <Exec/> to generate code. -->
<!-- See https://github.com/dotnet/project-system/blob/master/docs/design-time-builds.md -->
<Target AfterTarget="ResolveProjectReferences" Name="DoWhatIMean">
  <!-- May also need to _pick_ a supported Config and not assume web api and client projects share a configuration. -->
  <!-- See https://github.com/Microsoft/msbuild/blob/a0817cf07a805ee3f929f19b9336a2d3544cbd84/src/Tasks/Microsoft.Common.CurrentVersion.targets#L1829-L1844 -->
  <MSBuild target="GetMeThatStuff" 
       Project="@(ProjectReference)"
       RemoveProperties="TargetFramework;TargetFrameworks;RuntimeIdentifier" 
       Condition=" '%(OpenApiReference)' == 'true' ">
     <Output items="OpenApiReference" />
  </MSBuild>
</Target>

On the server side, disabling build in old-style (WebApi) projects may require a bit more work. Would need " '$(BuildingProject)' != 'true' " condition there.