From 7e05dd64bf1dcdb38d82ad1a64fc536c9884e457 Mon Sep 17 00:00:00 2001
From: David Hall <dahall@byu.net>
Date: Fri, 14 Jun 2024 14:55:36 -0400
Subject: [PATCH] BREAKING CHANGES: Guid.KnownFolderId() and
 Environment.SpecialFolder.KnownFolderId were changed to return null when
 value is not found rather than throwing an exception.

---
 PInvoke/Shell32/KnownFolderIdExt.cs | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/PInvoke/Shell32/KnownFolderIdExt.cs b/PInvoke/Shell32/KnownFolderIdExt.cs
index 41b8a543..645bb0c7 100644
--- a/PInvoke/Shell32/KnownFolderIdExt.cs
+++ b/PInvoke/Shell32/KnownFolderIdExt.cs
@@ -46,9 +46,8 @@ public static class KnownFolderIdExt
 	/// <param name="guid">The unique identifier representing a known folder.</param>
 	/// <returns>A corresponding <see cref="KNOWNFOLDERID"/>, if found. If not, an exception is thrown.</returns>
 	/// <exception cref="ArgumentOutOfRangeException">guid - Provided GUID value does not correspond to a known folder.</exception>
-	public static KNOWNFOLDERID KnownFolderId(this Guid guid) => 
-		AssociateAttribute.TryEnumLookup<KNOWNFOLDERID>(guid, out var kf) ? kf :
-		throw new ArgumentOutOfRangeException(nameof(guid), "Provided GUID value does not correspond to a known folder.");
+	public static KNOWNFOLDERID? KnownFolderId(this Guid guid) =>
+		AssociateAttribute.TryEnumLookup<KNOWNFOLDERID>(guid, out var kf) ? kf : null;
 
 	/// <summary>Gets a registry property associated with this known folder.</summary>
 	/// <typeparam name="T">Return type.</typeparam>
@@ -66,13 +65,13 @@ public static class KnownFolderIdExt
 	/// <summary>Retrieves the <see cref="KNOWNFOLDERID"/> associated with the <see cref="Environment.SpecialFolder"/>.</summary>
 	/// <param name="spFolder">The <see cref="Environment.SpecialFolder"/>.</param>
 	/// <returns>Matching <see cref="KNOWNFOLDERID"/>.</returns>
-	public static KNOWNFOLDERID KnownFolderId(this Environment.SpecialFolder spFolder)
+	public static KNOWNFOLDERID? KnownFolderId(this Environment.SpecialFolder spFolder)
 	{
 		if (spFolder == Environment.SpecialFolder.Personal) return KNOWNFOLDERID.FOLDERID_Documents;
 		if (spFolder == Environment.SpecialFolder.DesktopDirectory) return KNOWNFOLDERID.FOLDERID_Desktop;
 		foreach (KNOWNFOLDERID val in Enum.GetValues(typeof(KNOWNFOLDERID)).Cast<KNOWNFOLDERID>())
 			if (val.SpecialFolder() == spFolder) return val;
-		throw new InvalidCastException(@"There is not a Known Folder equivalent to this SpecialFolder.");
+		return null;
 	}
 
 	/// <summary>Retrieves the name associated with a <see cref="KNOWNFOLDERID"/>.</summary>