Adjust and document exit codes by JanKrivanek · Pull Request #4787 · dotnet/templating

JanKrivanek · 2022-05-25T17:21:06Z

Problem

Fixes #3186
Fixes #4253

Solution

Used well know exit codes where applicable
Defined user exit codes in 100-106 for others
Reviewed usages of NewCommandStatus, fixed some of the controversial usages
Documented our exit codes
Created aka.ms alias link pointing to our help (once merged)
Added spitting of help link in case of nonzero exit

Checks: N/A

Added unit tests
Added #nullable enable to all the modified files ?

vlada-shubina

please consider also parsing errors in exit codes, feels like 102 and 103 may be merged.

src/Microsoft.TemplateEngine.Cli/LocalizableStrings.resx

src/Microsoft.TemplateEngine.Cli/Commands/BaseCommand.cs

docs/Exit-Codes.md

src/Microsoft.TemplateEngine.Cli/NewCommandStatus.cs

docs/Exit-Codes.md

vlada-shubina · 2022-05-27T14:39:04Z

templating/src/Microsoft.TemplateEngine.Cli/TemplatePackageCoordinator.cs

Lines 714 to 840 in 7137e04

    
           private async Task DisplayInstallResultAsync(string packageToInstall, InstallerOperationResult result, ParseResult parseResult, CancellationToken cancellationToken) 
        
           { 
        
               if (string.IsNullOrWhiteSpace(packageToInstall)) 
        
               { 
        
                   throw new ArgumentException(nameof(packageToInstall)); 
        
               } 
        
               _ = result ?? throw new ArgumentNullException(nameof(result)); 
        
               cancellationToken.ThrowIfCancellationRequested(); 
        
               if (result.Success) 
        
               { 
        
                   IEnumerable<ITemplateInfo> templates = await _templatePackageManager.GetTemplatesAsync(result.TemplatePackage, cancellationToken).ConfigureAwait(false); 
        
                   if (templates.Any()) 
        
                   { 
        
                       Reporter.Output.WriteLine( 
        
                           string.Format( 
        
                               LocalizableStrings.TemplatePackageCoordinator_lnstall_Info_Success, 
        
                               result.TemplatePackage.DisplayName)); 
        
                       TemplateGroupDisplay.DisplayTemplateList( 
        
                           _engineEnvironmentSettings, 
        
                           templates, 
        
                           new TabularOutputSettings(_engineEnvironmentSettings.Environment), 
        
                           reporter: Reporter.Output); 
        
                   } 
        
                   else 
        
                   { 
        
                       Reporter.Output.WriteLine(string.Format( 
        
                               LocalizableStrings.TemplatePackageCoordinator_lnstall_Warning_No_Templates_In_Package, 
        
                               result.TemplatePackage.DisplayName)); 
        
                   } 
        
               } 
        
               else 
        
               { 
        
                   switch (result.Error) 
        
                   { 
        
                       case InstallerErrorCode.InvalidSource: 
        
                           Reporter.Error.WriteLine( 
        
                               string.Format( 
        
                                   LocalizableStrings.TemplatePackageCoordinator_lnstall_Error_InvalidNuGetFeeds, 
        
                                   packageToInstall, 
        
                                   result.ErrorMessage).Bold().Red()); 
        
                           break; 
        
                       case InstallerErrorCode.PackageNotFound: 
        
                           Reporter.Error.WriteLine( 
        
                               string.Format( 
        
                                   LocalizableStrings.TemplatePackageCoordinator_lnstall_Error_PackageNotFound, 
        
                                   packageToInstall).Bold().Red()); 
        
                           break; 
        
                       case InstallerErrorCode.DownloadFailed: 
        
                           Reporter.Error.WriteLine( 
        
                               string.Format( 
        
                                   LocalizableStrings.TemplatePackageCoordinator_lnstall_Error_DownloadFailed, 
        
                                   packageToInstall).Bold().Red()); 
        
                           break; 
        
                       case InstallerErrorCode.UnsupportedRequest: 
        
                           Reporter.Error.WriteLine( 
        
                               string.Format( 
        
                                   LocalizableStrings.TemplatePackageCoordinator_lnstall_Error_UnsupportedRequest, 
        
                                   packageToInstall).Bold().Red()); 
        
                           break; 
        
                       case InstallerErrorCode.AlreadyInstalled: 
        
                           Reporter.Error.WriteLine( 
        
                                 string.Format( 
        
                                     LocalizableStrings.TemplatePackageCoordinator_lnstall_Error_AlreadyInstalled, 
        
                                     packageToInstall).Bold().Red()); 
        
                           Reporter.Error.WriteLine(string.Format(LocalizableStrings.TemplatePackageCoordinator_lnstall_Error_AlreadyInstalled_Hint, InstallCommand.ForceOption.Aliases.First())); 
        
                           Reporter.Error.WriteCommand(Example.For<InstallCommand>(parseResult).WithArgument(BaseInstallCommand.NameArgument, packageToInstall).WithOption(BaseInstallCommand.ForceOption)); 
        
                           break; 
        
                       case InstallerErrorCode.UpdateUninstallFailed: 
        
                           Reporter.Error.WriteLine( 
        
                                 string.Format( 
        
                                     LocalizableStrings.TemplatePackageCoordinator_lnstall_Error_UninstallFailed, 
        
                                     packageToInstall).Bold().Red()); 
        
                           break; 
        
                       case InstallerErrorCode.InvalidPackage: 
        
                           Reporter.Error.WriteLine( 
        
                                 string.Format( 
        
                                     LocalizableStrings.TemplatePackageCoordinator_lnstall_Error_InvalidPackage, 
        
                                     packageToInstall).Bold().Red()); 
        
                           break; 
        
                       case InstallerErrorCode.GenericError: 
        
                       default: 
        
                           Reporter.Error.WriteLine( 
        
                               string.Format( 
        
                                   LocalizableStrings.TemplatePackageCoordinator_lnstall_Error_GenericError, 
        
                                   packageToInstall).Bold().Red()); 
        
                           break; 
        
                   } 
        
               } 
        
           } 
        
           private void HandleUpdateCheckErrors(InstallerOperationResult result, bool ignoreLocalPackageNotFound) 
        
           { 
        
               switch (result.Error) 
        
               { 
        
                   case InstallerErrorCode.InvalidSource: 
        
                       Reporter.Error.WriteLine( 
        
                           string.Format( 
        
                               LocalizableStrings.TemplatePackageCoordinator_Update_Error_InvalidNuGetFeeds, 
        
                               result.TemplatePackage.DisplayName).Bold().Red()); 
        
                       break; 
        
                   case InstallerErrorCode.PackageNotFound: 
        
                       if (!ignoreLocalPackageNotFound || !result.TemplatePackage.IsLocalPackage) 
        
                       { 
        
                           Reporter.Error.WriteLine( 
        
                               string.Format( 
        
                                   LocalizableStrings.TemplatePackageCoordinator_Update_Error_PackageNotFound, 
        
                                   result.TemplatePackage.DisplayName).Bold().Red()); 
        
                       } 
        
                       break; 
        
                   case InstallerErrorCode.UnsupportedRequest: 
        
                       Reporter.Error.WriteLine( 
        
                           string.Format( 
        
                               LocalizableStrings.TemplatePackageCoordinator_Update_Error_PackageNotSupported, 
        
                               result.TemplatePackage.DisplayName).Bold().Red()); 
        
                       break; 
        
                   case InstallerErrorCode.GenericError: 
        
                   default: 
        
                       Reporter.Error.WriteLine( 
        
                           string.Format( 
        
                               LocalizableStrings.TemplatePackageCoordinator_Update_Error_GenericError, 
        
                               result.TemplatePackage.DisplayName, 
        
                               result.ErrorMessage).Bold().Red()); 
        
                       break; 
        
               } 
        
           }

Template package failure may be one of the following. Just wondering if different codes make sense here.
E.g. in case download problem, it might be retried; however if package is not found or already installed retry won't help.

JanKrivanek · 2022-05-30T17:09:42Z

Template package failure may be one of the following. Just wondering if different codes make sense here. E.g. in case download problem, it might be retried; however if package is not found or already installed retry won't help.

Makes sense - I distinguished NotFound case.
Other cases might bee too low level of details for exit code (details are in log if needed).

It would be great if we could distinguish retriable from nonretriable errors by exit codes - unfortunately the DownloadError is still too generic of an error (it includes cases of download file already exist, any generic exception during download, etc.). The nuget API we use (CopyNupkgToStreamAsync), doesn't seem to surface the information - so we'd need a more thorough rework that's beyond scope of this change.

vlada-shubina · 2022-06-01T10:51:55Z

docs/Exit-Codes.md

+```
+
+
+## <a name="102"></a>102 - Missing required option(s) and/or argument(s) for the command


i'm still not convinced here. For example below, the command misses required argument, and exit code is 127; as it is managed by parser.

PS > dotnet new install Required argument missing for command: install Description: Installs a template package. Usage: dotnet new install [<package>...] [options] Arguments: <package> NuGet package ID or path to folder or NuGet package to install. To install the NuGet package of certain version, use <package ID>::<version>. Options: --interactive Allows the command to stop and wait for user input or action (for example to complete authentication). --add-source, --nuget-source <nuget-source> Specifies a NuGet source to use during install. --force Allows installing template packages from the specified sources even if they would override a template package from another source. -?, -h, --help Show command line help. PS > $LASTEXITCODE 127

Search command validation should be moved as the validator. I can work on it next month in scope of parser migration.

docs/Exit-Codes.md

vlada-shubina

Looks good.

Still not too convinced about keeping 102 for now, but i believe we can adjust later on if needed.

Adjust and document exit codes

758381f

JanKrivanek requested a review from vlada-shubina May 25, 2022 17:21

JanKrivanek requested review from a team and baronfel as code owners May 25, 2022 17:21

Add missing anchors

c8a32ea

JanKrivanek mentioned this pull request May 25, 2022

Exit codes review #4776

Closed

2 tasks

Update Exit-Codes.md

9db3b7d

vlada-shubina requested changes May 27, 2022

View reviewed changes

vlada-shubina reviewed May 27, 2022

View reviewed changes

docs/Exit-Codes.md Outdated Show resolved Hide resolved

JanKrivanek mentioned this pull request May 30, 2022

[CLI] review exit codes sent via New3CommandResult enum #3186

Closed

JanKrivanek added 2 commits May 30, 2022 18:59

Improve changes based on PR

1402d7b

Merge branch 'main' into exit-codes

de6fbb3

JanKrivanek requested a review from vlada-shubina May 30, 2022 17:01

JanKrivanek added 2 commits May 31, 2022 20:05

Fix usages of exit codes, improve documentation

f923656

Fix tests

c2f9202

vlada-shubina reviewed Jun 1, 2022

View reviewed changes

docs/Exit-Codes.md Show resolved Hide resolved

vlada-shubina reviewed Jun 1, 2022

View reviewed changes

docs/Exit-Codes.md Outdated Show resolved Hide resolved

vlada-shubina reviewed Jun 1, 2022

View reviewed changes

docs/Exit-Codes.md Outdated Show resolved Hide resolved

JanKrivanek mentioned this pull request Jun 1, 2022

Unify handling of missing parameter(s)/option(s) #4806

Open

Update description

645f0f1

JanKrivanek requested a review from vlada-shubina June 1, 2022 16:44

JanKrivanek added 2 commits June 2, 2022 14:07

Merge branch 'main' into exit-codes

946fdef

Fix tests after merge

a3f3dea

vlada-shubina approved these changes Jun 6, 2022

View reviewed changes

JanKrivanek merged commit d635904 into dotnet:main Jun 7, 2022

JanKrivanek deleted the exit-codes branch June 7, 2022 10:42

baronfel mentioned this pull request Jul 26, 2022

Add errors handling scenario for json output spec NuGet/Home#11983

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adjust and document exit codes#4787

Adjust and document exit codes#4787
JanKrivanek merged 10 commits intodotnet:mainfrom
JanKrivanek:exit-codes

JanKrivanek commented May 25, 2022

Uh oh!

vlada-shubina left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vlada-shubina commented May 27, 2022

Uh oh!

JanKrivanek commented May 30, 2022

Uh oh!

vlada-shubina Jun 1, 2022

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vlada-shubina left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		```


		## <a name="102"></a>102 - Missing required option(s) and/or argument(s) for the command

Conversation

JanKrivanek commented May 25, 2022

Problem

Solution

Checks: N/A

Uh oh!

vlada-shubina left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vlada-shubina commented May 27, 2022

Uh oh!

JanKrivanek commented May 30, 2022

Uh oh!

vlada-shubina Jun 1, 2022

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vlada-shubina left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants