OpenAPI ServiceReference Tool (#12810)

Add ServiceReference tool

.vscode/settings.json

@@ -1,9 +1,9 @@
 {
-    "files.trimTrailingWhitespace": true,
-    "files.associations": {
-        "*.*proj": "xml",
-        "*.props": "xml",
-        "*.targets": "xml",
-        "*.tasks": "xml"
-    }
+  "files.trimTrailingWhitespace": true,
+  "files.associations": {
+    "*.*proj": "xml",
+    "*.props": "xml",
+    "*.targets": "xml",
+    "*.tasks": "xml"
+  }
 }

eng/Build.props

@@ -28,6 +28,7 @@
     <!-- These projects are meant to be executed by tests. -->
     <ProjectToExclude Include="
                       $(RepoRoot)src\Tools\dotnet-watch\test\TestProjects\**\*.csproj;
+                      $(RepoRoot)src\Tools\Tests.Common\TestProjects\**\*.csproj;
                       $(RepoRoot)src\Razor\Razor.Design\test\testassets\**\*.*proj;
                       $(RepoRoot)src\submodules\**\*.*proj;
                       $(RepoRoot)src\Installers\**\*.*proj;

eng/Dependencies.props

@@ -149,7 +149,9 @@ and are generated based on the last package release.
   </ItemGroup>
 
   <ItemGroup Label="MSBuild">
+    <LatestPackageReference Include="Microsoft.Build" Version="$(MicrosoftBuildPackageVersion)" />
     <LatestPackageReference Include="Microsoft.Build.Framework" Version="$(MicrosoftBuildFrameworkPackageVersion)" />
+    <LatestPackageReference Include="Microsoft.Build.Locator" Version="$(MicrosoftBuildLocatorPackageVersion)" />
     <LatestPackageReference Include="Microsoft.Build.Utilities.Core" Version="$(MicrosoftBuildUtilitiesCorePackageVersion)" />
   </ItemGroup>
 
@@ -172,6 +174,7 @@ and are generated based on the last package release.
     <LatestPackageReference Include="Moq" Version="$(MoqPackageVersion)" />
     <LatestPackageReference Include="Newtonsoft.Json" Version="$(NewtonsoftJsonPackageVersion)" />
     <LatestPackageReference Include="Newtonsoft.Json.Bson" Version="$(NewtonsoftJsonBsonPackageVersion)" />
+    <LatestPackageReference Include="NSwag.ApiDescription.Client" Version="$(NSwagApiDescriptionClientPackageVersion)" />
     <LatestPackageReference Include="Selenium.Support" Version="$(SeleniumSupportPackageVersion)" />
     <LatestPackageReference Include="Selenium.WebDriver" Version="$(SeleniumWebDriverPackageVersion)" />
     <LatestPackageReference Include="Selenium.WebDriver.ChromeDriver" Version="$(SeleniumWebDriverChromeDriverPackageVersion)" />

eng/Signing.props

@@ -97,6 +97,12 @@
     <_DotNetFilesToExclude Include="$(RedistNetCorePath)dotnet.exe" CertificateName="None" />
     <FileSignInfo Include="@(_DotNetFilesToExclude->'%(FileName)%(Extension)'->Distinct())" CertificateName="None" />
 
+    <!--
+      We include the Microsoft.Build.Locator.dll assembly in our global tool 'Microsoft.dotnet-openapi'.
+      It is already signed by that team, so we don't need to sign it.
+    -->
+    <FileSignInfo Include="Microsoft.Build.Locator.dll" CertificateName="None" />
+
     <!--
       We include the Microsoft.Data.SqlClient.dll assembly in our global tool 'dotnet-sql-cache'.
       It is already signed by that team, so we don't need to sign it.

eng/Versions.props

@@ -196,7 +196,9 @@
     <!-- Partner teams -->
     <MicrosoftAzureKeyVaultPackageVersion>2.3.2</MicrosoftAzureKeyVaultPackageVersion>
     <MicrosoftAzureStorageBlobPackageVersion>10.0.1</MicrosoftAzureStorageBlobPackageVersion>
+    <MicrosoftBuildPackageVersion>15.8.166</MicrosoftBuildPackageVersion>
     <MicrosoftBuildFrameworkPackageVersion>15.8.166</MicrosoftBuildFrameworkPackageVersion>
+    <MicrosoftBuildLocatorPackageVersion>1.2.6</MicrosoftBuildLocatorPackageVersion>
     <MicrosoftBuildUtilitiesCorePackageVersion>15.8.166</MicrosoftBuildUtilitiesCorePackageVersion>
     <MicrosoftCodeAnalysisCommonPackageVersion>3.0.0</MicrosoftCodeAnalysisCommonPackageVersion>
     <MicrosoftCodeAnalysisCSharpPackageVersion>3.0.0</MicrosoftCodeAnalysisCSharpPackageVersion>
@@ -232,6 +234,7 @@
     <MonoCecilPackageVersion>0.10.1</MonoCecilPackageVersion>
     <NewtonsoftJsonBsonPackageVersion>1.0.2</NewtonsoftJsonBsonPackageVersion>
     <NewtonsoftJsonPackageVersion>12.0.1</NewtonsoftJsonPackageVersion>
+    <NSwagApiDescriptionClientPackageVersion>13.0.4</NSwagApiDescriptionClientPackageVersion>
     <SeleniumSupportPackageVersion>3.12.1</SeleniumSupportPackageVersion>
     <SeleniumWebDriverMicrosoftDriverPackageVersion>17.17134.0</SeleniumWebDriverMicrosoftDriverPackageVersion>
     <SeleniumWebDriverChromeDriverPackageVersion>2.43.0</SeleniumWebDriverChromeDriverPackageVersion>

src/Shared/Process/ProcessExtensions.cs

@@ -1,8 +1,9 @@
-// Copyright (c) .NET Foundation. All rights reserved.
+// Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
 using System.Collections.Generic;
+using System.ComponentModel;
 using System.Diagnostics;
 using System.IO;
 using System.Runtime.InteropServices;
@@ -41,42 +42,56 @@ public static void KillTree(this Process process, TimeSpan timeout)
 
         private static void GetAllChildIdsUnix(int parentId, ISet<int> children, TimeSpan timeout)
         {
-            RunProcessAndWaitForExit(
-                "pgrep",
-                $"-P {parentId}",
-                timeout,
-                out var stdout);
-
-            if (!string.IsNullOrEmpty(stdout))
+            try
             {
-                using (var reader = new StringReader(stdout))
+                RunProcessAndWaitForExit(
+                    "pgrep",
+                    $"-P {parentId}",
+                    timeout,
+                    out var stdout);
+
+                if (!string.IsNullOrEmpty(stdout))
                 {
-                    while (true)
+                    using (var reader = new StringReader(stdout))
                     {
-                        var text = reader.ReadLine();
-                        if (text == null)
+                        while (true)
                         {
-                            return;
-                        }
+                            var text = reader.ReadLine();
+                            if (text == null)
+                            {
+                                return;
+                            }
 
-                        if (int.TryParse(text, out var id))
-                        {
-                            children.Add(id);
-                            // Recursively get the children
-                            GetAllChildIdsUnix(id, children, timeout);
+                            if (int.TryParse(text, out var id))
+                            {
+                                children.Add(id);
+                                // Recursively get the children
+                                GetAllChildIdsUnix(id, children, timeout);
+                            }
                         }
                     }
                 }
             }
+            catch (Win32Exception ex) when (ex.Message.Contains("No such file or directory"))
+            {
+                // This probably means that pgrep isn't installed. Nothing to be done?
+            }
         }
 
         private static void KillProcessUnix(int processId, TimeSpan timeout)
         {
-            RunProcessAndWaitForExit(
-                "kill",
-                $"-TERM {processId}",
-                timeout,
-                out var stdout);
+            try
+            {
+                RunProcessAndWaitForExit(
+                    "kill",
+                    $"-TERM {processId}",
+                    timeout,
+                    out var stdout);
+            }
+            catch (Win32Exception ex) when (ex.Message.Contains("No such file or directory"))
+            {
+                // This probably means that the process is already dead
+            }
         }
 
         private static void RunProcessAndWaitForExit(string fileName, string arguments, TimeSpan timeout, out string stdout)

src/Tools/Microsoft.dotnet-openapi/README.md

@@ -0,0 +1,84 @@
+# Microsoft.dotnet-openapi
+
+`Microsoft.dotnet-openapi` is a tool for managing OpenAPI references within your project.
+
+## Commands
+
+### Add Commands
+
+<!-- TODO: Restore after https://github.com/aspnet/AspNetCore/issues/12738
+ #### Add Project
+
+##### Options
+
+| Short option | Long option | Description | Example |
+|-------|------|-------|---------|
+| -v|--verbose | Show verbose output. |dotnet openapi add project *-v* ../Ref/ProjRef.csproj |
+| -p|--project | The project to operate on. |dotnet openapi add project *--project .\Ref.csproj* ../Ref/ProjRef.csproj |
+
+##### Arguments
+
+|  Argument  | Description | Example |
+|-------------|-------------|---------|
+| source-file | The source to create a reference from. Must be a project file. |dotnet openapi add project *../Ref/ProjRef.csproj* | -->
+
+#### Add File
+
+##### Options
+
+| Short option| Long option| Description | Example |
+|-------|------|-------|---------|
+| -v|--verbose | Show verbose output. |dotnet openapi add file *-v* .\OpenAPI.json |
+| -p|--updateProject | The project to operate on. |dotnet openapi add file *--updateProject .\Ref.csproj* .\OpenAPI.json |
+
+##### Arguments
+
+|  Argument  | Description | Example |
+|-------------|-------------|---------|
+| source-file | The source to create a reference from. Must be an OpenAPI file. |dotnet openapi add file *.\OpenAPI.json* |
+
+#### Add URL
+
+##### Options
+
+| Short option| Long option| Description | Example |
+|-------|------|-------------|---------|
+| -v|--verbose | Show verbose output. |dotnet openapi add url *-v* <http://contoso.com/openapi.json> |
+| -p|--updateProject | The project to operate on. |dotnet openapi add url *--updateProject .\Ref.csproj* <http://contoso.com/openapi.json> |
+| -o|--output-file | Where to place the local copy of the OpenAPI file. |dotnet openapi add url <https://contoso.com/openapi.json> *--output-file myclient.json* |
+
+##### Arguments
+
+|  Argument  | Description | Example |
+|-------------|-------------|---------|
+| source-file | The source to create a reference from. Must be a URL. |dotnet openapi add url <https://contoso.com/openapi.json> |
+
+### Remove
+
+##### Options
+
+| Short option| Long option| Description| Example |
+|-------|------|------------|---------|
+| -v|--verbose | Show verbose output. |dotnet openapi remove *-v*|
+| -p|--updateProject | The project to operate on. |dotnet openapi remove *--updateProject .\Ref.csproj* .\OpenAPI.json |
+
+#### Arguments
+
+|  Argument  | Description| Example |
+| ------------|------------|---------|
+| source-file | The source to remove the reference to. |dotnet openapi remove *.\OpenAPI.json* |
+
+### Refresh
+
+#### Options
+
+| Short option| Long option| Description | Example |
+|-------|------|-------------|---------|
+| -v|--verbose | Show verbose output. | dotnet openapi refresh *-v* <https://contoso.com/openapi.json> |
+| -p|--updateProject | The project to operate on. | dotnet openapi refresh *--updateProject .\Ref.csproj* <https://contoso.com/openapi.json> |
+
+#### Arguments
+
+|  Argument  | Description | Example |
+| ------------|-------------|---------|
+| source-file | The URL to refresh the reference from. | dotnet openapi refresh *<https://contoso.com/openapi.json>* |

src/Tools/Microsoft.dotnet-openapi/src/Application.cs

@@ -0,0 +1,104 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+using System;
+using System.IO;
+using System.Reflection;
+using Microsoft.Build.Locator;
+using Microsoft.DotNet.Openapi.Tools;
+using Microsoft.DotNet.OpenApi.Commands;
+using Microsoft.Extensions.CommandLineUtils;
+
+namespace Microsoft.DotNet.OpenApi
+{
+    internal class Application : CommandLineApplication
+    {
+        static Application()
+        {
+            MSBuildLocator.RegisterDefaults();
+        }
+
+        public Application(
+            string workingDirectory,
+            IHttpClientWrapper httpClient,
+            TextWriter output = null,
+            TextWriter error = null)
+        {
+            Out = output ?? Out;
+            Error = error ?? Error;
+
+            WorkingDirectory = workingDirectory;
+
+            Name = "openapi";
+            FullName = "OpenApi reference management tool";
+            Description = "OpenApi reference management operations.";
+            ShortVersionGetter = GetInformationalVersion;
+
+            Help = HelpOption("-?|-h|--help");
+            Help.Inherited = true;
+
+            Invoke = () =>
+            {
+                ShowHelp();
+                return 0;
+            };
+
+            Commands.Add(new AddCommand(this, httpClient));
+            Commands.Add(new RemoveCommand(this, httpClient));
+            Commands.Add(new RefreshCommand(this, httpClient));
+        }
+
+        public string WorkingDirectory { get; }
+
+        public CommandOption Help { get; }
+
+        public new int Execute(params string[] args)
+        {
+            try
+            {
+                return base.Execute(args);
+            }
+            catch (AggregateException ex) when (ex.InnerException != null)
+            {
+                foreach (var innerException in ex.InnerExceptions)
+                {
+                    Error.WriteLine(ex.InnerException.Message);
+                }
+                return 1;
+            }
+
+            catch (ArgumentException ex)
+            {
+                // Don't show a call stack when we have unneeded arguments, just print the error message.
+                // The code that throws this exception will print help, so no need to do it here.
+                Error.WriteLine(ex.Message);
+                return 1;
+            }
+            catch (CommandParsingException ex)
+            {
+                // Don't show a call stack when we have unneeded arguments, just print the error message.
+                // The code that throws this exception will print help, so no need to do it here.
+                Error.WriteLine(ex.Message);
+                return 1;
+            }
+            catch (OperationCanceledException)
+            {
+                // This is a cancellation, not a failure.
+                Error.WriteLine("Cancelled");
+                return 1;
+            }
+            catch (Exception ex)
+            {
+                Error.WriteLine(ex);
+                return 1;
+            }
+        }
+
+        private string GetInformationalVersion()
+        {
+            var assembly = typeof(Application).GetTypeInfo().Assembly;
+            var attribute = assembly.GetCustomAttribute<AssemblyInformationalVersionAttribute>();
+            return attribute.InformationalVersion;
+        }
+    }
+}

src/Tools/Microsoft.dotnet-openapi/src/CodeGenerator.cs

@@ -0,0 +1,11 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+
+namespace Microsoft.DotNet.OpenApi
+{
+    public enum CodeGenerator
+    {
+        NSwagCSharp,
+        NSwagTypeScript
+    }
+}