Improve publish error message when public network access is disabled (#4807)

* Initial plan

* Improve publish action error message for SSL/network connection failures

When public networking is disabled for an Azure Function App, deployments
fail with the unhelpful 'The SSL connection could not be established, see
inner exception.' message.

This change:
- Adds PublishNetworkingError constant with an improved message explaining
  the likely cause and an aka.ms link for guidance
- Wraps publish operations in RunAsync() with an HttpRequestException catch
  that provides the improved error message while preserving the original
  error details

Co-authored-by: liliankasem <2198905+liliankasem@users.noreply.github.com>

* Update networking docs link and add release note entry for PR #4807

Co-authored-by: liliankasem <2198905+liliankasem@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: liliankasem <2198905+liliankasem@users.noreply.github.com>
Co-authored-by: Lilian Kasem <likasem@microsoft.com>

Author: Copilot

release_notes.md

@@ -24,4 +24,5 @@
   - Support for custom bundle download paths via `AzureFunctionsJobHost__extensionBundle__downloadPath` environment variable
 - Added `--bundles-channel` option to `func init` command to specify extension bundle channel (GA, Preview, or Experimental) during project initialization
 - Fallback to cached bundles if there is no network connection during `func start` (#4772)
-  - Added global `--offline` variable to run in offline mode (#4772)
+- Added global `--offline` variable to run in offline mode (#4772)
+- Improved error message for `func azure functionapp publish` when the connection fails due to networking restrictions, with a link to networking options documentation. (#4807)

src/Cli/func/Actions/AzureActions/PublishFunctionAppAction.cs

@@ -2,6 +2,7 @@
 // Licensed under the MIT License. See LICENSE in the project root for license information.
 
 using System.Globalization;
+using System.Net.Http;
 using System.Net.Http.Handlers;
 using System.Net.Http.Headers;
 using Azure.Functions.Cli.Actions.LocalActions;
@@ -240,13 +241,22 @@ public override async Task RunAsync()
             }
             else
             {
-                if (PublishLocalSettingsOnly)
+                try
                 {
-                    await PublishLocalAppSettings(functionApp, additionalAppSettings);
+                    if (PublishLocalSettingsOnly)
+                    {
+                        await PublishLocalAppSettings(functionApp, additionalAppSettings);
+                    }
+                    else
+                    {
+                        await PublishFunctionApp(functionApp, ignoreParser, additionalAppSettings);
+                    }
                 }
-                else
+                catch (HttpRequestException ex)
                 {
-                    await PublishFunctionApp(functionApp, ignoreParser, additionalAppSettings);
+                    // HttpRequestException is thrown for connectivity failures (SSL, socket, DNS)
+                    // not for HTTP status errors, which are handled by CheckResponseStatusAsync as CliException.
+                    throw new CliException($"{Constants.Errors.PublishNetworkingError}{Environment.NewLine}Details: {ex.Message}", ex);
                 }
             }
         }

src/Cli/func/Common/Constants.cs

@@ -143,6 +143,7 @@ public static class Errors
             public const string EitherPidOrAllMustBeSpecified = "Must specify either -a/--all or -p/--processId <Pid>";
             public const string ExtensionsNeedDotnet = "Extensions command requires dotnet on your path. Please make sure to install dotnet (.NET Core SDK) for your system from https://www.microsoft.com/net/download";
             public const string UnableToUpdateAppSettings = "Error updating Application Settings for the Function App for deployment.";
+            public const string PublishNetworkingError = "Unable to connect to the Azure Function App. If public network access is disabled for this app, ensure you are deploying from an authorized network. For more information, see https://learn.microsoft.com/azure/azure-functions/functions-networking-options";
             public const string WebJobsStorageNotFound = "Missing value for AzureWebJobsStorage in {0}. This is required for all triggers other than {1}. You can run 'func azure functionapp fetch-app-settings <functionAppName>' or specify a connection string in {2}.";
             public const string WebJobsStorageNotFoundWithUserSecrets = "Missing value for AzureWebJobsStorage in {0} and User Secrets. This is required for all triggers other than {1}. You can run 'func azure functionapp fetch-app-settings <functionAppName>' or specify a connection string in {2} or User Secrets.";
             public const string AppSettingNotFound = "Warning: Cannot find value named '{0}' in {1} that matches '{2}' property set on '{3}' in '{4}'. You can run 'func azure functionapp fetch-app-settings <functionAppName>' or specify a connection string in {5}.";