Mirror the ShellLinkFile setup for InternetShortcutFile.

Author: mjr4077au

src/PSADT/PSADT.Interop/ComTypes/IUniformResourceLocatorW.cs

@@ -0,0 +1,35 @@
+using System.Diagnostics.CodeAnalysis;
+using System.Runtime.InteropServices;
+using Windows.Win32.UI.Shell;
+
+namespace PSADT.Interop.ComTypes
+{
+    /// <summary>
+    /// Provides Unicode methods for setting and retrieving URLs in an Internet shortcut.
+    /// </summary>
+    [ComImport, Guid("CABB0DA1-DA57-11CF-9974-0020AFD79762")]
+    [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+    [CoClass(typeof(InternetShortcut))]
+    [SuppressMessage("Interoperability", "SYSLIB1096:Convert to 'GeneratedComInterface'", Justification = "GeneratedComInterfaceAttribute is not available in .NET Framework 4.7.2.")]
+    internal interface IUniformResourceLocatorW
+    {
+        /// <summary>
+        /// Sets the URL of the Internet shortcut.
+        /// </summary>
+        /// <param name="pcszURL">The URL string to set.</param>
+        /// <param name="dwInFlags">Flags that control URL validation and canonicalization.</param>
+        void SetURL([MarshalAs(UnmanagedType.LPWStr)] string pcszURL, IURL_SETURL_FLAGS dwInFlags);
+
+        /// <summary>
+        /// Gets the URL of the Internet shortcut.
+        /// </summary>
+        /// <param name="ppszURL">Receives the URL string. The caller must free this memory using CoTaskMemFree.</param>
+        void GetURL([MarshalAs(UnmanagedType.LPWStr)] out string? ppszURL);
+
+        /// <summary>
+        /// Invokes a command on the URL (e.g., opens the URL in a browser).
+        /// </summary>
+        /// <param name="purlici">A reference to a <see cref="URLINVOKECOMMANDINFOW"/> structure specifying the command to invoke.</param>
+        void InvokeCommand(in URLINVOKECOMMANDINFOW purlici);
+    }
+}

src/PSADT/PSADT.Interop/ComTypes/InternetShortcut.cs

@@ -0,0 +1,13 @@
+using System.Runtime.InteropServices;
+
+namespace PSADT.Interop.ComTypes
+{
+    /// <summary>
+    /// The InternetShortcut coclass for creating and manipulating .url files.
+    /// </summary>
+    [ComImport, Guid("FBF23B40-E3F0-101B-8488-00AA003E56F8")]
+    [ClassInterface(ClassInterfaceType.None)]
+    internal class InternetShortcut
+    {
+    }
+}

src/PSADT/PSADT.Interop/IURL_INVOKECOMMAND_FLAGS.cs

@@ -0,0 +1,53 @@
+using System;
+
+namespace PSADT.Interop
+{
+    /// <summary>
+    /// Defines flags that specify how a command should be invoked on a URL.
+    /// </summary>
+    /// <remarks>These flags are used with the IURL_INVOKECOMMAND method to control the behavior of the
+    /// command invocation, such as allowing user interface interaction, using the default verb, waiting for DDE
+    /// conversations, enabling asynchronous execution, and logging usage for telemetry purposes.</remarks>
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Naming", "CA1707:Identifiers should not contain underscores", Justification = "This is how they're named in the Win32 API.")]
+    [Flags]
+    public enum IURL_INVOKECOMMAND_FLAGS
+    {
+        /// <summary>
+        /// Specifies that the command can display a user interface when invoked.
+        /// </summary>
+        /// <remarks>This flag is used in conjunction with the IURL_INVOKECOMMAND method to indicate that
+        /// the command may require user interaction.</remarks>
+        IURL_INVOKECOMMAND_FL_ALLOW_UI = Windows.Win32.UI.Shell.IURL_INVOKECOMMAND_FLAGS.IURL_INVOKECOMMAND_FL_ALLOW_UI,
+
+        /// <summary>
+        /// Specifies that the default verb should be used when invoking a command on a URL.
+        /// </summary>
+        /// <remarks>This value is part of the IURL_INVOKECOMMAND_FLAGS enumeration and indicates that the
+        /// default action associated with the URL will be executed. Use this flag when you want to perform the standard
+        /// operation defined for the URL, such as opening it in a browser or launching the associated
+        /// application.</remarks>
+        IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB = Windows.Win32.UI.Shell.IURL_INVOKECOMMAND_FLAGS.IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB,
+
+        /// <summary>
+        /// Specifies that the command should wait for a Dynamic Data Exchange (DDE) conversation to complete before
+        /// returning control to the caller.
+        /// </summary>
+        /// <remarks>Use this flag with the IURL_INVOKECOMMAND method to ensure synchronous execution.
+        /// When set, the caller will not proceed until the DDE conversation has finished, which may be necessary when
+        /// interacting with applications that require DDE communication.</remarks>
+        IURL_INVOKECOMMAND_FL_DDEWAIT = Windows.Win32.UI.Shell.IURL_INVOKECOMMAND_FLAGS.IURL_INVOKECOMMAND_FL_DDEWAIT,
+
+        /// <summary>
+        /// Specifies that the command can be invoked asynchronously without blocking the calling thread.
+        /// </summary>
+        /// <remarks>Use this flag to indicate that the operation may be performed in a non-blocking
+        /// manner, allowing for asynchronous execution. This is useful when the command might take a significant amount
+        /// of time to complete and you want to maintain responsiveness in the calling application.</remarks>
+        IURL_INVOKECOMMAND_FL_ASYNCOK = Windows.Win32.UI.Shell.IURL_INVOKECOMMAND_FLAGS.IURL_INVOKECOMMAND_FL_ASYNCOK,
+
+        /// <summary>
+        /// Records the usage of the command for telemetry purposes, allowing for analysis of how often and in what contexts the command is invoked.
+        /// </summary>
+        IURL_INVOKECOMMAND_FL_LOG_USAGE = Windows.Win32.UI.Shell.IURL_INVOKECOMMAND_FLAGS.IURL_INVOKECOMMAND_FL_LOG_USAGE,
+    }
+}

src/PSADT/PSADT.Interop/NativeMethods.txt

@@ -131,6 +131,8 @@ IsProcessInJob
 IsWindowEnabled
 IsWindowVisible
 ITaskService
+IURL_INVOKECOMMAND_FLAGS
+IURL_SETURL_FLAGS
 JOB_OBJECT_MSG_ABNORMAL_EXIT_PROCESS
 JOB_OBJECT_MSG_ACTIVE_PROCESS_LIMIT
 JOB_OBJECT_MSG_ACTIVE_PROCESS_ZERO
@@ -2107,6 +2109,7 @@ TOKEN_USER
 TreeResetNamedSecurityInfo
 UNICODE_STRING
 UpdateProcThreadAttribute
+URLINVOKECOMMANDINFOW
 VARENUM
 VER_NT_DOMAIN_CONTROLLER
 VER_NT_SERVER

src/PSADT/PSADT/ShortcutManagement/InternetShortcutFile.cs

@@ -0,0 +1,263 @@
+using System;
+using System.IO;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+using PSADT.Interop.ComTypes;
+using PSADT.Interop.Extensions;
+using PSADT.Interop.SafeHandles;
+using Windows.Win32;
+using Windows.Win32.Foundation;
+using Windows.Win32.System.Com;
+using Windows.Win32.UI.Shell;
+
+namespace PSADT.ShortcutManagement
+{
+    /// <summary>
+    /// Provides a managed wrapper around the Windows InternetShortcut COM interface.
+    /// This class enables creating, loading, modifying, and saving Internet shortcut (.url) files.
+    /// </summary>
+    /// <remarks>
+    /// This class wraps the <c>IUniformResourceLocatorW</c> and <c>IPersistFile</c> COM interfaces
+    /// to provide access to URL shortcut properties.
+    /// </remarks>
+    public sealed class InternetShortcutFile : IDisposable
+    {
+        /// <summary>
+        /// Creates a new, empty Internet shortcut.
+        /// </summary>
+        /// <returns>A new <see cref="InternetShortcutFile"/> instance.</returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static InternetShortcutFile New()
+        {
+            return new();
+        }
+
+        /// <summary>
+        /// Creates a new Internet shortcut with the specified URL.
+        /// </summary>
+        /// <param name="url">The URL for the shortcut.</param>
+        /// <returns>A new <see cref="InternetShortcutFile"/> instance with the URL set.</returns>
+        public static InternetShortcutFile New(Uri url)
+        {
+            ArgumentNullException.ThrowIfNull(url);
+            return new() { Url = url };
+        }
+
+        /// <summary>
+        /// Loads an existing Internet shortcut file in read-only mode.
+        /// </summary>
+        /// <param name="filePath">The path to the shortcut file to load.</param>
+        /// <returns>A new <see cref="InternetShortcutFile"/> instance loaded from the specified file.</returns>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="filePath"/> is null.</exception>
+        /// <exception cref="ArgumentException">Thrown when <paramref name="filePath"/> is empty or whitespace.</exception>
+        /// <exception cref="FileNotFoundException">Thrown when the specified file does not exist.</exception>
+        /// <exception cref="COMException">Thrown when the COM operation fails.</exception>
+        /// <remarks>Use <see cref="Load(string, Interop.STGM)"/> with <see cref="Interop.STGM.STGM_READWRITE"/> if you need to modify the shortcut.</remarks>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static InternetShortcutFile Load(string filePath)
+        {
+            return Load(filePath, Interop.STGM.STGM_READ);
+        }
+
+        /// <summary>
+        /// Loads an existing Internet shortcut file with the specified storage mode.
+        /// </summary>
+        /// <param name="filePath">The path to the shortcut file to load.</param>
+        /// <param name="storageMode">The storage mode flags.</param>
+        /// <returns>A new <see cref="InternetShortcutFile"/> instance loaded from the specified file.</returns>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="filePath"/> is null.</exception>
+        /// <exception cref="ArgumentException">Thrown when <paramref name="filePath"/> is empty or whitespace.</exception>
+        /// <exception cref="FileNotFoundException">Thrown when the specified file does not exist.</exception>
+        /// <exception cref="COMException">Thrown when the COM operation fails.</exception>
+        public static InternetShortcutFile Load(string filePath, Interop.STGM storageMode)
+        {
+            ArgumentException.ThrowIfNullOrWhiteSpace(filePath);
+            if (!File.Exists(filePath))
+            {
+                throw new FileNotFoundException("The specified shortcut file does not exist.", filePath);
+            }
+            InternetShortcutFile internetShortcut = new();
+            try
+            {
+                ((IPersistFile)internetShortcut._internetShortcut).Load(filePath, (STGM)storageMode);
+                return internetShortcut;
+            }
+            catch
+            {
+                internetShortcut.Dispose();
+                throw;
+            }
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="InternetShortcutFile"/> class.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        private InternetShortcutFile()
+        {
+            _internetShortcut = new IUniformResourceLocatorW();
+        }
+
+        /// <summary>
+        /// Finalizes an instance of the <see cref="InternetShortcutFile"/> class.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        ~InternetShortcutFile()
+        {
+            Dispose(false);
+        }
+
+        /// <summary>
+        /// Saves the Internet shortcut to the currently loaded file path.
+        /// </summary>
+        /// <exception cref="InvalidOperationException">Thrown when no file path has been set.</exception>
+        /// <exception cref="COMException">Thrown when the COM operation fails.</exception>
+        public void Save()
+        {
+            ObjectDisposedException.ThrowIf(_disposed, this);
+            string? currentFile = FilePath;
+            if (string.IsNullOrWhiteSpace(currentFile))
+            {
+                throw new InvalidOperationException("No file path has been set. Use Save(string) to specify a path.");
+            }
+            Save(currentFile!);
+        }
+
+        /// <summary>
+        /// Saves the Internet shortcut to the specified file path.
+        /// </summary>
+        /// <param name="filePath">The path where the shortcut file should be saved.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="filePath"/> is null.</exception>
+        /// <exception cref="ArgumentException">Thrown when <paramref name="filePath"/> is empty or whitespace.</exception>
+        /// <exception cref="COMException">Thrown when the COM operation fails.</exception>
+        public void Save(string filePath)
+        {
+            ObjectDisposedException.ThrowIf(_disposed, this);
+            ArgumentException.ThrowIfNullOrWhiteSpace(filePath);
+            ((IPersistFile)_internetShortcut).Save(filePath, true);
+        }
+
+        /// <summary>
+        /// Gets the path of the currently loaded shortcut file.
+        /// </summary>
+        /// <value>The full path to the shortcut file, or <see langword="null"/> if no file has been loaded or saved.</value>
+        public string? FilePath
+        {
+            get
+            {
+                ObjectDisposedException.ThrowIf(_disposed, this);
+                ((IPersistFile)_internetShortcut).GetCurFile(out SafeCoTaskMemHandle? ppszFileName);
+                using (ppszFileName)
+                {
+                    return ppszFileName?.ToStringUni();
+                }
+            }
+        }
+
+        /// <summary>
+        /// Gets or sets the URL of the Internet shortcut.
+        /// </summary>
+        /// <value>The URL that the shortcut points to.</value>
+        /// <exception cref="COMException">Thrown when the COM operation fails.</exception>
+        public Uri? Url
+        {
+            get
+            {
+                ObjectDisposedException.ThrowIf(_disposed, this);
+                _internetShortcut.GetURL(out string? url);
+                return url is not null ? new(url) : null;
+            }
+            set
+            {
+                ObjectDisposedException.ThrowIf(_disposed, this);
+                ArgumentNullException.ThrowIfNull(value);
+                _internetShortcut.SetURL(value.AbsoluteUri, 0);
+            }
+        }
+
+        /// <summary>
+        /// Opens the URL using the default handler.
+        /// </summary>
+        /// <exception cref="COMException">Thrown when the COM operation fails.</exception>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void Invoke()
+        {
+            Invoke(null, default, Interop.IURL_INVOKECOMMAND_FLAGS.IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB);
+        }
+
+        /// <summary>
+        /// Opens the URL using the specified verb.
+        /// </summary>
+        /// <param name="verb">The verb to invoke (e.g., "open"). Pass <see langword="null"/> for the default verb.</param>
+        /// <exception cref="COMException">Thrown when the COM operation fails.</exception>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void Invoke(string? verb)
+        {
+            Invoke(verb, default, verb is null ? Interop.IURL_INVOKECOMMAND_FLAGS.IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB : 0);
+        }
+
+        /// <summary>
+        /// Opens the URL using the specified verb and options.
+        /// </summary>
+        /// <param name="verb">The verb to invoke (e.g., "open"). Pass <see langword="null"/> for the default verb.</param>
+        /// <param name="hwndParent">A handle to the parent window for any UI that may be displayed.</param>
+        /// <param name="flags">Flags that control the invocation behavior.</param>
+        /// <exception cref="COMException">Thrown when the COM operation fails.</exception>
+        public void Invoke(string? verb, nint hwndParent, Interop.IURL_INVOKECOMMAND_FLAGS flags)
+        {
+            ObjectDisposedException.ThrowIf(_disposed, this);
+            unsafe
+            {
+                fixed (char* pVerb = verb)
+                {
+                    URLINVOKECOMMANDINFOW commandInfo = new()
+                    {
+                        dwcbSize = (uint)sizeof(URLINVOKECOMMANDINFOW),
+                        dwFlags = (uint)flags,
+                        hwndParent = (HWND)hwndParent,
+                        pcszVerb = pVerb
+                    };
+                    _internetShortcut.InvokeCommand(in commandInfo);
+                }
+            }
+        }
+
+        /// <summary>
+        /// Releases all resources used by the <see cref="InternetShortcutFile"/>.
+        /// </summary>
+        public void Dispose()
+        {
+            Dispose(true);
+            GC.SuppressFinalize(this);
+        }
+
+        /// <summary>
+        /// Releases the unmanaged resources used by the <see cref="InternetShortcutFile"/> and optionally releases the managed resources.
+        /// </summary>
+        /// <param name="disposing"><see langword="true"/> to release both managed and unmanaged resources; <see langword="false"/> to release only unmanaged resources.</param>
+        private void Dispose(bool disposing)
+        {
+            if (!_disposed)
+            {
+                if (disposing)
+                {
+                    if (_internetShortcut != null)
+                    {
+                        _ = Marshal.FinalReleaseComObject(_internetShortcut);
+                    }
+                }
+                _disposed = true;
+            }
+        }
+
+        /// <summary>
+        /// Indicates whether the object has been disposed.
+        /// </summary>
+        private bool _disposed;
+
+        /// <summary>
+        /// The underlying IUniformResourceLocatorW COM object.
+        /// </summary>
+        private readonly IUniformResourceLocatorW _internetShortcut;
+    }
+}