fix: ConvertValue returns default instead of throwing on incompatible string conversions

Convention-matched string properties that name-match numeric or enum
destinations (e.g. string MonitorObjectId -> int? MonitorObjectId) no
longer throw FormatException or ArgumentException at map-time.

ConvertValue now uses Enum.TryParse for string->enum and wraps
Convert.ChangeType in a try/catch, returning default(T) on failure.

Author: rolandbanks

CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ## [Unreleased]
 
+## [10.0.16] - 2026-03-31
+
+### Fixed
+
+- `ConvertValue` no longer throws `FormatException`/`ArgumentException` when convention-matched string properties can't convert to numeric or enum destinations - returns `default(T)` instead
+
 ## [10.0.15] - 2026-03-31
 
 ### Added

PanoramicData.Mapper.Test/ConventionMismatchTests.cs

@@ -0,0 +1,108 @@
+using PanoramicData.Mapper.Test.Models;
+
+namespace PanoramicData.Mapper.Test;
+
+public class ConventionMismatchTests
+{
+	// --- string "" -> int (FormatException repro) ---
+
+	[Fact]
+	public void Map_EmptyStringToInt_DefaultsToZero()
+	{
+		var config = new MapperConfiguration(cfg =>
+			cfg.AddProfile(new StringToIntProfile()));
+		var mapper = config.CreateMapper();
+
+		var source = new StringPropertySource { MonitorObjectId = "" };
+		var dest = mapper.Map<MismatchedNumericDestination>(source);
+
+		dest.MonitorObjectId.Should().Be(0);
+	}
+
+	[Fact]
+	public void Map_ValidStringToInt_ConvertsCorrectly()
+	{
+		var config = new MapperConfiguration(cfg =>
+			cfg.AddProfile(new StringToIntProfile()));
+		var mapper = config.CreateMapper();
+
+		var source = new StringPropertySource { MonitorObjectId = "42", Count = "7" };
+		var dest = mapper.Map<MismatchedNumericDestination>(source);
+
+		dest.MonitorObjectId.Should().Be(42);
+		dest.Count.Should().Be(7);
+	}
+
+	// --- string "" -> int? (FormatException repro) ---
+
+	[Fact]
+	public void Map_EmptyStringToNullableInt_DefaultsToNull()
+	{
+		var config = new MapperConfiguration(cfg =>
+			cfg.AddProfile(new StringToNullableIntProfile()));
+		var mapper = config.CreateMapper();
+
+		var source = new StringPropertySource { MonitorObjectId = "" };
+		var dest = mapper.Map<MismatchedNullableIntDestination>(source);
+
+		dest.MonitorObjectId.Should().BeNull();
+	}
+
+	// --- string "" -> enum (ArgumentException repro) ---
+
+	[Fact]
+	public void Map_EmptyStringToEnum_DefaultsToFirstValue()
+	{
+		var config = new MapperConfiguration(cfg =>
+			cfg.AddProfile(new StringToEnumMismatchProfile()));
+		var mapper = config.CreateMapper();
+
+		var source = new StringPropertySource { GroupStatus = "" };
+		var dest = mapper.Map<MismatchedEnumDestination>(source);
+
+		dest.GroupStatus.Should().Be(ResourceGroupStatusType.Unknown);
+	}
+
+	[Fact]
+	public void Map_InvalidStringToEnum_DefaultsToFirstValue()
+	{
+		var config = new MapperConfiguration(cfg =>
+			cfg.AddProfile(new StringToEnumMismatchProfile()));
+		var mapper = config.CreateMapper();
+
+		var source = new StringPropertySource { GroupStatus = "NotAValidEnumMember" };
+		var dest = mapper.Map<MismatchedEnumDestination>(source);
+
+		dest.GroupStatus.Should().Be(ResourceGroupStatusType.Unknown);
+	}
+
+	[Fact]
+	public void Map_ValidStringToEnum_ConvertsCorrectly()
+	{
+		var config = new MapperConfiguration(cfg =>
+			cfg.AddProfile(new StringToEnumMismatchProfile()));
+		var mapper = config.CreateMapper();
+
+		var source = new StringPropertySource { GroupStatus = "Active" };
+		var dest = mapper.Map<MismatchedEnumDestination>(source);
+
+		dest.GroupStatus.Should().Be(ResourceGroupStatusType.Active);
+	}
+
+	// --- Profiles ---
+
+	private class StringToIntProfile : Profile
+	{
+		public StringToIntProfile() => CreateMap<StringPropertySource, MismatchedNumericDestination>();
+	}
+
+	private class StringToNullableIntProfile : Profile
+	{
+		public StringToNullableIntProfile() => CreateMap<StringPropertySource, MismatchedNullableIntDestination>();
+	}
+
+	private class StringToEnumMismatchProfile : Profile
+	{
+		public StringToEnumMismatchProfile() => CreateMap<StringPropertySource, MismatchedEnumDestination>();
+	}
+}

PanoramicData.Mapper.Test/Models/TestModels.cs

@@ -644,4 +644,36 @@ public class DataSourceGraphStoreItem : IdentifiedStoreItem
 	public required string Title { get; set; }
 	public required int Width { get; set; }
 	public bool IsActive { get; set; }
+}
+
+// --- Convention mismatch models (string -> numeric/enum by name) ---
+
+public enum ResourceGroupStatusType
+{
+	Unknown,
+	Active,
+	Inactive
+}
+
+public class StringPropertySource
+{
+	public string MonitorObjectId { get; set; } = string.Empty;
+	public string GroupStatus { get; set; } = string.Empty;
+	public string Count { get; set; } = string.Empty;
+}
+
+public class MismatchedNumericDestination
+{
+	public int MonitorObjectId { get; set; }
+	public int Count { get; set; }
+}
+
+public class MismatchedNullableIntDestination
+{
+	public int? MonitorObjectId { get; set; }
+}
+
+public class MismatchedEnumDestination
+{
+	public ResourceGroupStatusType GroupStatus { get; set; }
 }

PanoramicData.Mapper/Internal/TypeMap.cs

@@ -674,7 +674,14 @@ private static bool IsAssignableOrConvertible(Type sourceType, Type destType)
 		// String -> enum
 		if (valueType == typeof(string) && dstCore.IsEnum)
 		{
-			return Enum.Parse(dstCore, (string)value);
+			var str = (string)value;
+			if (str.Length > 0 && Enum.TryParse(dstCore, str, out var parsed))
+			{
+				return parsed;
+			}
+
+			// Unparseable string - return default for the enum
+			return Activator.CreateInstance(destType) ?? Activator.CreateInstance(dstCore)!;
 		}
 
 		// Integral -> enum (Convert.ChangeType cannot handle this)
@@ -686,7 +693,15 @@ private static bool IsAssignableOrConvertible(Type sourceType, Type destType)
 		// Enum -> integral, numeric widening/narrowing, string -> numeric, etc.
 		if (value is IConvertible)
 		{
-			return Convert.ChangeType(value, dstCore);
+			try
+			{
+				return Convert.ChangeType(value, dstCore);
+			}
+			catch (Exception ex) when (ex is FormatException or InvalidCastException or OverflowException)
+			{
+				// Conversion failed (e.g. empty string -> int) - return default
+				return destType.IsValueType ? Activator.CreateInstance(destType) : null;
+			}
 		}
 
 		return value;