Allow WSLC networks to be referenced by name, Id, or Id prefix (#42046)

* Allow WSLC networks to be referenced by name or Id

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Resolve network full Id before name to match engine precedence

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add WSLC_E_NETWORK_PREFIX_AMBIGUOUS error code for ambiguous network prefixes

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Resolve built-in networks by ID or prefix at container create

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Resolve network prefixes via engine, reject host IDs, and check aliases before lookup

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Inspect networks by reference in a single engine round trip

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Move network resolution into WSLCSession and resolve container networks through it

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: ggarzia-MSFT

doc/docs/api-reference/c/error-codes.md

@@ -23,6 +23,7 @@
 #define WSLC_E_CONTAINER_DELETED MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 19)             /* 0x80040613 */
 #define WSLC_E_CAPABILITY_ADDITIONS_DISABLED MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 20) /* 0x80040614 */
 #define WSLC_E_RUNTIME_UPDATE_NEEDED MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 21)         /* 0x80040615 */
+#define WSLC_E_NETWORK_PREFIX_AMBIGUOUS MAKE_HRESULT(SEVERITY_ERROR, FACILITY_ITF, WSLC_E_BASE + 22)      /* 0x80040616 */
 ```
 
 | Symbol | Hex Value |
@@ -49,5 +50,6 @@
 | `WSLC_E_CONTAINER_DELETED` | `0x80040613` |
 | `WSLC_E_CAPABILITY_ADDITIONS_DISABLED` | `0x80040614` |
 | `WSLC_E_RUNTIME_UPDATE_NEEDED` | `0x80040615` |
+| `WSLC_E_NETWORK_PREFIX_AMBIGUOUS` | `0x80040616` |
 
 ---

doc/docs/api-reference/c/network-apis/wslcdeletesessionnetwork.md

@@ -1,18 +1,20 @@
 # WslcDeleteSessionNetwork
 
 ```c
-STDAPI WslcDeleteSessionNetwork(_In_ WslcSession session, _In_z_ PCSTR name, _Outptr_opt_result_z_ PWSTR* errorMessage);
+STDAPI WslcDeleteSessionNetwork(_In_ WslcSession session, _In_z_ PCSTR nameOrId, _Outptr_opt_result_z_ PWSTR* errorMessage);
 ```
 
 | Parameter | Type | Direction |
 |---|---|---|
 | `session` | `WslcSession` | in |
-| `name` | `PCSTR` | in |
+| `nameOrId` | `PCSTR` | in |
 | `errorMessage` | `PWSTR*` | out, optional |
 
 Return value: `HRESULT`.
 
-Returns `WSLC_E_NETWORK_NOT_FOUND` if the network does not exist, or `HRESULT_FROM_WIN32(ERROR_SHARING_VIOLATION)` if a container is connected to the network. Returns [`WSLC_E_RUNTIME_UPDATE_NEEDED`](../error-codes.md) if the installed WSL runtime does not support network management.
+`nameOrId` is the name, full ID, or unique ID prefix of the network to delete. An exact ID match takes precedence over a name match, and a name match takes precedence over an ID prefix match.
+
+Returns `WSLC_E_NETWORK_NOT_FOUND` if no network matches, `WSLC_E_NETWORK_PREFIX_AMBIGUOUS` if an ID prefix matches more than one network, or `HRESULT_FROM_WIN32(ERROR_SHARING_VIOLATION)` if a container is connected to the network. Returns [`WSLC_E_RUNTIME_UPDATE_NEEDED`](../error-codes.md) if the installed WSL runtime does not support network management.
 
 Example:
 

doc/docs/api-reference/cpp/core-classes/session.md

@@ -200,7 +200,7 @@ auto network = session.CreateNetwork(NetworkSettings{L"backend"});
 
 ## Session::DeleteNetwork(hstring)
 
-Deletes a network from the session. Throws `WSLC_E_NETWORK_NOT_FOUND` if the network does not exist.
+Deletes a network from the session by name, full ID, or unique ID prefix. An exact ID match takes precedence over a name match, and a name match takes precedence over an ID prefix match. Throws `WSLC_E_NETWORK_NOT_FOUND` if no network matches, or `WSLC_E_NETWORK_PREFIX_AMBIGUOUS` if an ID prefix matches more than one network.
 
 ```cpp
 session.DeleteNetwork(L"backend");

doc/docs/api-reference/cpp/enumerations/error.md

@@ -19,3 +19,4 @@
 | `ContainerDeleted` | `-2147219949` | `0x80040613` | The container was deleted. |
 | `CapabilityAdditionsDisabled` | `-2147219948` | `0x80040614` | Capability additions are disabled by policy |
 | `RuntimeUpdateNeeded` | `-2147219947` | `0x80040615` | The requested feature requires a newer WSL runtime. |
+| `NetworkPrefixAmbiguous` | `-2147219946` | `0x80040616` | The network ID prefix matches more than one network. |

doc/docs/api-reference/csharp/core-classes/session.md

@@ -30,7 +30,7 @@ public sealed class Session : IDisposable
     public IReadOnlyList<ImageInfo> GetImages();
     public IReadOnlyList<NetworkInfo> GetNetworks();
     public NetworkInfo CreateNetwork(NetworkSettings settings);
-    public void DeleteNetwork(string name);
+    public void DeleteNetwork(string nameOrId);
     public void Dispose();
 }
 ```
@@ -249,9 +249,9 @@ Creates a bridge network in the session and returns it. Throws `HRESULT_FROM_WIN
 var network = session.CreateNetwork(new NetworkSettings("backend"));
 ```
 
-## Session.DeleteNetwork(string name)
+## Session.DeleteNetwork(string nameOrId)
 
-Deletes a network from the session. Throws `WSLC_E_NETWORK_NOT_FOUND` if the network does not exist.
+Deletes a network from the session by name, full ID, or unique ID prefix. An exact ID match takes precedence over a name match, and a name match takes precedence over an ID prefix match. Throws `WSLC_E_NETWORK_NOT_FOUND` if no network matches, or `WSLC_E_NETWORK_PREFIX_AMBIGUOUS` if an ID prefix matches more than one network.
 
 ```csharp
 session.DeleteNetwork("backend");

doc/docs/api-reference/csharp/enumerations/error.md

@@ -19,3 +19,4 @@
 | `ContainerDeleted` | `-2147219949` | `0x80040613` | The container was deleted. |
 | `CapabilityAdditionsDisabled` | `-2147219948` | `0x80040614` | Capability additions are disabled by policy |
 | `RuntimeUpdateNeeded` | `-2147219947` | `0x80040615` | The requested feature requires a newer WSL runtime. |
+| `NetworkPrefixAmbiguous` | `-2147219946` | `0x80040616` | The network ID prefix matches more than one network. |

localization/strings/en-US/Resources.resw

@@ -2514,6 +2514,10 @@ For privacy information about this product please visit https://aka.ms/privacy.<
     <value>Network not found: '{}'</value>
     <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment>
   </data>
+  <data name="MessageWslcNetworkPrefixAmbiguous" xml:space="preserve">
+    <value>Multiple networks match '{}'; use a longer ID or the network name.</value>
+    <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment>
+  </data>
   <data name = "MessageWslcInvalidNetworkDriver" xml:space = "preserve" >
     <value>Unsupported network driver: '{}'</value>
     <comment>{FixedPlaceholder="{}"}Command line arguments, file names and string inserts should not be translated</comment>
@@ -3820,6 +3824,9 @@ On first run, creates the file with all settings commented out at their defaults
   <data name="WSLCCLI_NetworkNameArgDescription" xml:space="preserve">
     <value>Network name</value>
   </data>
+  <data name="WSLCCLI_NetworkNameOrIdArgDescription" xml:space="preserve">
+    <value>Network name or ID</value>
+  </data>
   <data name="WSLCCLI_NetworkListQuietArgDesc" xml:space="preserve">
     <value>Only display network IDs</value>
   </data>

src/windows/WslcSDK/winrt/Session.cpp

@@ -440,17 +440,17 @@ winrt::Microsoft::WSL::Containers::NetworkInfo Session::CreateNetwork(winrt::Mic
     return winrt::make<implementation::NetworkInfo>(networkInfo);
 }
 
-void Session::DeleteNetwork(hstring const& name)
+void Session::DeleteNetwork(hstring const& nameOrId)
 {
-    if (name.empty())
+    if (nameOrId.empty())
     {
-        throw winrt::hresult_invalid_argument(L"Network name cannot be empty");
+        throw winrt::hresult_invalid_argument(L"Network name or ID cannot be empty");
     }
 
     EnsureStarted();
 
     wil::unique_cotaskmem_string errorMessage;
-    auto hr = WslcDeleteSessionNetwork(ToHandle(), winrt::to_string(name).c_str(), errorMessage.put());
+    auto hr = WslcDeleteSessionNetwork(ToHandle(), winrt::to_string(nameOrId).c_str(), errorMessage.put());
     THROW_MSG_IF_FAILED(hr, errorMessage);
 }
 

src/windows/WslcSDK/winrt/Session.h

@@ -45,7 +45,7 @@ struct Session : SessionT<Session>
     winrt::Windows::Foundation::Collections::IVectorView<winrt::Microsoft::WSL::Containers::ImageInfo> GetImages();
     winrt::Windows::Foundation::Collections::IVectorView<winrt::Microsoft::WSL::Containers::NetworkInfo> GetNetworks();
     winrt::Microsoft::WSL::Containers::NetworkInfo CreateNetwork(winrt::Microsoft::WSL::Containers::NetworkSettings const& settings);
-    void DeleteNetwork(hstring const& name);
+    void DeleteNetwork(hstring const& nameOrId);
     winrt::event_token Terminated(winrt::Microsoft::WSL::Containers::SessionTerminationHandler const& handler);
     void Terminated(winrt::event_token const& token) noexcept;
     winrt::event_token ProcessCrashed(winrt::Microsoft::WSL::Containers::ProcessCrashHandler const& handler);

src/windows/WslcSDK/winrt/wslcsdk.idl

@@ -93,7 +93,7 @@ namespace Microsoft.WSL.Containers
 
         IVectorView<NetworkInfo> GetNetworks();
         NetworkInfo CreateNetwork(NetworkSettings settings);
-        void DeleteNetwork(String name);
+        void DeleteNetwork(String nameOrId);
 
         event SessionTerminationHandler Terminated;
         event ProcessCrashHandler ProcessCrashed;
@@ -453,5 +453,6 @@ namespace Microsoft.WSL.Containers
         ContainerDeleted = 0x80040613,
         CapabilityAdditionsDisabled = 0x80040614,
         RuntimeUpdateNeeded = 0x80040615,
+        NetworkPrefixAmbiguous = 0x80040616,
     };
 }