Address immediate issues in service reference feature (#12366)

- #12363
- correct a few VS issues
- void silent failures
- improve documentation
- support the `clean` target
- stop using experimentatal package version

src/Mvc/Extensions.ApiDescription.Client/src/Microsoft.Extensions.ApiDescription.Client.csproj

@@ -9,7 +9,6 @@
     <PackageId>$(MSBuildProjectName)</PackageId>
     <PackageTags>Build Tasks;MSBuild;Swagger;Open API;code generation; Web API client</PackageTags>
     <IsShippingPackage>true</IsShippingPackage>
-    <VersionPrefix>$(ExperimentalVersionPrefix)</VersionPrefix>
     <TargetFrameworks>netstandard2.0;net461</TargetFrameworks>
     <DevelopmentDependency>true</DevelopmentDependency>
     <HasReferenceAssembly>false</HasReferenceAssembly>

src/Mvc/Extensions.ApiDescription.Client/src/build/Microsoft.Extensions.ApiDescription.Client.props

@@ -67,9 +67,6 @@
     Well-known metadata of the code generator item groups.
   -->
   <ItemDefinitionGroup>
-    <!-- OpenApiProjectReference items may also include OpenApiReference metadata. -->
-    <OpenApiProjectReference />
-
     <OpenApiReference>
       <!-- Name of the class to generate. Defaults to match filename in %(OutputPath). -->
       <ClassName />
@@ -98,5 +95,40 @@
       -->
       <OutputPath />
     </OpenApiReference>
+
+    <!-- OpenApiProjectReference items may include all OpenApiReference metadata. -->
+    <OpenApiProjectReference>
+      <!--
+        Name of the class to generate. Defaults to match filename in %(OutputPath). To avoid compilation errors,
+        override only if the referenced project has a single registered document.
+      -->
+      <ClassName />
+
+      <!--
+        Code generator to use. Required and must end with "CSharp" or "TypeScript" (the currently-supported target
+        languages) unless %(OutputPath) is set. Builds will invoke a target named "Generate%(CodeGenerator)" to do
+        actual code generation.
+      -->
+      <CodeGenerator>NSwagCSharp</CodeGenerator>
+
+      <!-- Namespace to contain generated class. Default is $(RootNamespace). -->
+      <Namespace />
+
+      <!--
+        Options to pass to the code generator target then (likely) added to a tool's command line. Value is passed
+        along to the code generator but otherwise unused in this package.
+      -->
+      <Options>$(OpenApiGenerateCodeOptions)</Options>
+
+      <!--
+        Path to place generated code. Code generator may interpret path as a filename or directory. Default filename or
+        folder name is {document filename}Client.[cs|ts]. {document filename} is always either %(Filename}.json (when
+        the document name is "v1") or %(Filename)_{document name}.json (otherwise). Filenames and relative paths (if
+        explicitly set) are combined with $(OpenApiCodeDirectory). Final value (depending on $(OpenApiCodeDirectory))
+        is likely to be a path relative to the client project. To avoid repeatedly writing to the same file, override
+        only if the referenced project has a single registered document.
+      -->
+      <OutputPath />
+    </OpenApiProjectReference>
   </ItemDefinitionGroup>
 </Project>

src/Mvc/Extensions.ApiDescription.Client/src/build/Microsoft.Extensions.ApiDescription.Client.targets

@@ -26,6 +26,7 @@
     -->
     <ProjectReference Include="@(OpenApiProjectReference)" Exclude="@(ProjectReference)">
       <GlobalPropertiesToRemove>TargetFramework</GlobalPropertiesToRemove>
+      <Private>false</Private>
       <ReferenceOutputAssembly>false</ReferenceOutputAssembly>
       <SkipGetTargetFrameworkProperties>true</SkipGetTargetFrameworkProperties>
     </ProjectReference>
@@ -128,6 +129,9 @@
         <SourceDocument>%(_Directories.FullPath)</SourceDocument>
       </Compile>
 
+      <FileWrites Exclude="@(FileWrites)"
+          Include="@(_Files);@(_Directories -> '%(Identity)/**/*.ts;%(Identity)/**/*.tsx;%(Identity)/**/*.$(DefaultLanguageSourceExtension)'" />
+
       <_Files Remove="@(_Files)" />
       <_Directories Remove="@(_Directories)" />
     </ItemGroup>

src/Mvc/Extensions.ApiDescription.Client/src/build/OpenApiItemsSchema.xaml

@@ -72,7 +72,7 @@
 
     <StringProperty Name="Link" Visible="false">
       <StringProperty.DataSource>
-        <DataSource SourceOfDefaultValue="AfterContext" />
+        <DataSource SourceOfDefaultValue="AfterContext" PersistenceStyle="Attribute" />
       </StringProperty.DataSource>
       <StringProperty.Metadata>
         <NameValuePair Name="DoNotCopyAcrossProjects" Value="true" />
@@ -88,6 +88,12 @@
       </StringProperty.DataSource>
     </StringProperty>
 
+    <StringProperty Name="CodeGenerator" Visible="false">
+      <StringProperty.DataSource>
+        <DataSource SourceOfDefaultValue="AfterContext" PersistenceStyle="Attribute" />
+      </StringProperty.DataSource>
+    </StringProperty>
+
     <StringProperty Name="Namespace" DisplayName="Namespace"
                     Category="CodeGen"
                     Description="Namespace to place the generated class in.">
@@ -158,6 +164,12 @@
 
     <BoolProperty Name="Visible" Visible="false" Default="true" />
 
+    <StringProperty Name="CodeGenerator" Visible="false">
+      <StringProperty.DataSource>
+        <DataSource SourceOfDefaultValue="AfterContext" PersistenceStyle="Attribute" />
+      </StringProperty.DataSource>
+    </StringProperty>
+
     <StringProperty Name="Namespace" DisplayName="Namespace"
                     Category="CodeGen"
                     Description="Namespace to place the generated classes in.">

src/Mvc/Extensions.ApiDescription.Server/src/Microsoft.Extensions.ApiDescription.Server.csproj

@@ -12,7 +12,6 @@
     <PackageId>$(MSBuildProjectName)</PackageId>
     <PackageTags>MSBuild;Swagger;Open API;code generation;Web API</PackageTags>
     <IsShippingPackage>true</IsShippingPackage>
-    <VersionPrefix>$(ExperimentalVersionPrefix)</VersionPrefix>
     <DevelopmentDependency>true</DevelopmentDependency>
 
     <!--

src/Mvc/Extensions.ApiDescription.Server/src/build/Microsoft.Extensions.ApiDescription.Server.targets

@@ -2,7 +2,7 @@
 <Project>
   <PropertyGroup Condition=" '$(OpenApiGenerateDocuments)' == '' ">
     <OpenApiGenerateDocuments
-        Condition=" '$(TargetFrameworkIdentifier)' == '.NETCoreApp' AND '$(_TargetFrameworkVersionWithoutV)' &lt; '2.1' ">false</OpenApiGenerateDocuments>
+        Condition=" '$(TargetFrameworkIdentifier)' == '.NETCoreApp' AND '$(TargetFrameworkVersion.TrimStart('vV'))' &lt; '2.1' ">false</OpenApiGenerateDocuments>
     <OpenApiGenerateDocuments Condition=" '$(OpenApiGenerateDocuments)' == '' ">true</OpenApiGenerateDocuments>
   </PropertyGroup>
   <PropertyGroup>
@@ -16,15 +16,24 @@
   </ItemGroup>
 
   <Target Name="OpenApiGetDocuments" Returns="@(_OpenApiProjectDocuments)">
+    <Error Text="OpenAPI document generation is disabled. Add '<OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>' to the project."
+        Condition=" '$(OpenApiGenerateDocuments)' != 'true' " />
+
     <ReadLinesFromFile File="$(_OpenApiDocumentsCache)">
       <Output TaskParameter="Lines" ItemName="_OpenApiProjectDocuments" />
     </ReadLinesFromFile>
+
+    <Warning Text="Application does not have any registered documents. Update its 'Startup' class to register a document."
+        Condition=" '@(_OpenApiProjectDocuments)' == '' " />
   </Target>
 
   <Target Name="GenerateOpenApiDocuments"
       Condition=" '$(OpenApiGenerateDocuments)' == 'true' "
       Inputs="$(TargetPath)"
       Outputs="$(_OpenApiDocumentsCache)">
+    <Error Text="OpenAPI document generation is not supported when targeting netcoreapp2.0 or earlier. Disable the feature or move to a later target framework."
+        Condition=" '$(TargetFrameworkIdentifier)' == '.NETCoreApp' AND '$(TargetFrameworkVersion.TrimStart('vV'))' &lt; '2.1' " />
+
     <PropertyGroup>
       <_Command>dotnet "$(MSBuildThisFileDirectory)/../tools/dotnet-getdocument.dll" --assembly "$(TargetPath)"</_Command>
       <_Command>$(_Command) --file-list "$(_OpenApiDocumentsCache)" --framework "$(TargetFrameworkMoniker)"</_Command>