Add FileNameFriendly property to DbaInstanceParameter for safe filenames (#31)

* Add FileNameFriendly property to DbaInstanceParameter for safe filenames

Fixes #30

When connecting via named pipes (e.g., .\SQLSERVER), the FullSmoName
property returns values like "NP:.$SQLSERVER" which contain colons -
invalid characters for Windows filenames. This causes Backup-DbaDbMasterKey
to create truncated filenames like "NP" instead of the intended name.

This commit adds a new FileNameFriendly property that sanitizes the
instance name for use in filenames by replacing invalid characters
(colons, backslashes, commas) with underscores.

Changes:
- Added FileNameFriendly property to DbaInstanceParameter class
- Updated existing tests to verify FileNameFriendly output
- Added comprehensive TestFileNameFriendly test covering various scenarios

The main dbatools repository can now use FileNameFriendly instead of
FullSmoName when generating backup filenames.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-authored-by: Chrissy LeMaire <[email protected]>

* Enhance FileNameFriendly with comprehensive character sanitization

- Use Path.GetInvalidFileNameChars() for comprehensive sanitization
- Now handles all invalid filename characters including IPv6 brackets
- Improved XML documentation with explicit character list
- Added edge case tests for IPv6 and IPv4 with ports
- Enhanced existing tests to verify no invalid characters remain

Implements code review recommendations from PR #31

Co-authored-by: Chrissy LeMaire <[email protected]>

---------

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

Author: potatoqualitee

project/dbatools.Tests/Parameter/DbaInstanceParamaterTest.cs

@@ -94,6 +94,7 @@ public void TestDotHostname()
             Assert.AreEqual(".", dbaInstanceParamater.FullName);
             Assert.IsTrue(dbaInstanceParamater.IsLocalHost);
             Assert.AreEqual("NP:.", dbaInstanceParamater.FullSmoName);
+            Assert.AreEqual("NP_.", dbaInstanceParamater.FileNameFriendly);
             Assert.AreEqual(@"MSSQLSERVER", dbaInstanceParamater.InstanceName);
             Assert.AreEqual(@"[MSSQLSERVER]", dbaInstanceParamater.SqlInstanceName);
             Assert.AreEqual(@"[.]", dbaInstanceParamater.SqlFullName);
@@ -115,6 +116,7 @@ public void TestDotHostnameWithInstance()
             Assert.AreEqual(@".\instancename", dbaInstanceParamater.FullName);
             Assert.IsTrue(dbaInstanceParamater.IsLocalHost);
             Assert.AreEqual(@"NP:.\instancename", dbaInstanceParamater.FullSmoName);
+            Assert.AreEqual(@"NP_._instancename", dbaInstanceParamater.FileNameFriendly);
             Assert.AreEqual(@"instancename", dbaInstanceParamater.InstanceName);
             Assert.AreEqual(@"[instancename]", dbaInstanceParamater.SqlInstanceName);
             Assert.AreEqual(@"[.\instancename]", dbaInstanceParamater.SqlFullName);
@@ -238,5 +240,81 @@ public void TestServerNameWithDash()
             Assert.AreEqual("[My-Instance.domain.local\\MyTestInstance]", dbaInstanceParamater.SqlFullName);
             Assert.IsFalse(dbaInstanceParamater.IsConnectionString);
         }
+
+        /// <summary>
+        /// Tests that FileNameFriendly returns valid filenames for various connection types
+        /// </summary>
+        [TestMethod]
+        public void TestFileNameFriendly()
+        {
+            // Test with named pipes using dot notation
+            var npDot = new DbaInstanceParameter(".");
+            Assert.AreEqual("NP_.", npDot.FileNameFriendly);
+            Assert.IsFalse(npDot.FileNameFriendly.Contains(":"));
+
+            // Test with named pipes using dot notation with instance
+            var npDotInstance = new DbaInstanceParameter(@".\SQLSERVER");
+            Assert.AreEqual("NP_._SQLSERVER", npDotInstance.FileNameFriendly);
+            Assert.IsFalse(npDotInstance.FileNameFriendly.Contains(":"));
+            Assert.IsFalse(npDotInstance.FileNameFriendly.Contains("\\"));
+
+            // Test with TCP protocol
+            var tcpInstance = new DbaInstanceParameter("TCP:server\\instance");
+            Assert.AreEqual("TCP_server_instance", tcpInstance.FileNameFriendly);
+            Assert.IsFalse(tcpInstance.FileNameFriendly.Contains(":"));
+            Assert.IsFalse(tcpInstance.FileNameFriendly.Contains("\\"));
+
+            // Test with port number
+            var withPort = new DbaInstanceParameter("server,1433");
+            Assert.AreEqual("server_1433", withPort.FileNameFriendly);
+            Assert.IsFalse(withPort.FileNameFriendly.Contains(","));
+
+            // Test with regular instance name (no protocol)
+            var regular = new DbaInstanceParameter("server\\instance");
+            Assert.AreEqual("server_instance", regular.FileNameFriendly);
+            Assert.IsFalse(regular.FileNameFriendly.Contains("\\"));
+
+            // Test that all results contain no invalid filename characters
+            var invalidChars = System.IO.Path.GetInvalidFileNameChars();
+            Assert.IsFalse(npDot.FileNameFriendly.IndexOfAny(invalidChars) >= 0);
+            Assert.IsFalse(npDotInstance.FileNameFriendly.IndexOfAny(invalidChars) >= 0);
+            Assert.IsFalse(tcpInstance.FileNameFriendly.IndexOfAny(invalidChars) >= 0);
+            Assert.IsFalse(withPort.FileNameFriendly.IndexOfAny(invalidChars) >= 0);
+            Assert.IsFalse(regular.FileNameFriendly.IndexOfAny(invalidChars) >= 0);
+        }
+
+        /// <summary>
+        /// Tests that FileNameFriendly handles edge cases including IPv6 addresses
+        /// </summary>
+        [TestMethod]
+        public void TestFileNameFriendlyEdgeCases()
+        {
+            // Test with IPv6 address (contains colons and brackets)
+            var ipv6 = new DbaInstanceParameter("::1");
+            var invalidChars = System.IO.Path.GetInvalidFileNameChars();
+            Assert.IsFalse(ipv6.FileNameFriendly.IndexOfAny(invalidChars) >= 0,
+                "IPv6 address FileNameFriendly should not contain invalid filename characters");
+
+            // Test with IPv6 address and port
+            var ipv6Port = new DbaInstanceParameter("[::1]:1433");
+            Assert.IsFalse(ipv6Port.FileNameFriendly.IndexOfAny(invalidChars) >= 0,
+                "IPv6 with port FileNameFriendly should not contain invalid filename characters");
+
+            // Test with regular IPv6 address
+            var ipv6Full = new DbaInstanceParameter("2001:0db8:85a3:0000:0000:8a2e:0370:7334");
+            Assert.IsFalse(ipv6Full.FileNameFriendly.IndexOfAny(invalidChars) >= 0,
+                "Full IPv6 address FileNameFriendly should not contain invalid filename characters");
+
+            // Test with IPv4 address and port (contains colon)
+            var ipv4Port = new DbaInstanceParameter("192.168.1.1:1433");
+            Assert.IsFalse(ipv4Port.FileNameFriendly.IndexOfAny(invalidChars) >= 0,
+                "IPv4 with port FileNameFriendly should not contain invalid filename characters");
+
+            // Test that the results are not empty
+            Assert.IsFalse(string.IsNullOrWhiteSpace(ipv6.FileNameFriendly));
+            Assert.IsFalse(string.IsNullOrWhiteSpace(ipv6Port.FileNameFriendly));
+            Assert.IsFalse(string.IsNullOrWhiteSpace(ipv6Full.FileNameFriendly));
+            Assert.IsFalse(string.IsNullOrWhiteSpace(ipv4Port.FileNameFriendly));
+        }
     }
 }

project/dbatools/Parameter/DbaInstanceParameter.cs

@@ -1,4 +1,6 @@
 using System;
+using System.IO;
+using System.Linq;
 using System.Management.Automation;
 using System.Net;
 using System.Net.NetworkInformation;
@@ -118,6 +120,49 @@ public string FullSmoName
             }
         }
 
+        /// <summary>
+        /// Full name of the instance sanitized for use in file names.
+        /// Replaces all Windows invalid filename characters (including : \ / | ? * " &lt; &gt;) with underscores.
+        /// Safe to use as part of a filename or path component.
+        /// </summary>
+        [ParameterContract(ParameterContractType.Field, ParameterContractBehavior.Mandatory)]
+        public string FileNameFriendly
+        {
+            get
+            {
+                string temp = _ComputerName;
+                if (_NetworkProtocol == SqlConnectionProtocol.NP) { temp = "NP_" + temp; }
+                if (_NetworkProtocol == SqlConnectionProtocol.TCP) { temp = "TCP_" + temp; }
+
+                string result;
+                if (!String.IsNullOrEmpty(_InstanceName) && _Port > 0)
+                {
+                    result = String.Format(@"{0}_{1}_{2}", temp, _InstanceName, _Port);
+                }
+                else if (_Port > 0)
+                {
+                    result = temp + "_" + _Port;
+                }
+                else if (!String.IsNullOrEmpty(_InstanceName))
+                {
+                    result = temp + "_" + _InstanceName;
+                }
+                else
+                {
+                    result = temp;
+                }
+
+                // Sanitize any remaining invalid filename characters
+                char[] invalidChars = Path.GetInvalidFileNameChars();
+                foreach (char c in invalidChars)
+                {
+                    result = result.Replace(c, '_');
+                }
+
+                return result;
+            }
+        }
+
         /// <summary>
         /// Name of the computer as used in an SQL Statement
         /// </summary>