Add friendly exception message when DismAddPackage returns CBS_E_NOT_…

…APPLICABLE (#93)

Add new exception with message and update documentation

Fixes #92

src/Microsoft.Dism.Tests/DismExceptionTest.cs

@@ -23,6 +23,16 @@ public void DismOpenSessionsExceptionTest()
             VerifyDismException<DismOpenSessionsException>(DismApi.DISMAPI_E_OPEN_SESSION_HANDLES, Resources.DismExceptionMessageOpenSessions);
         }
 
+        [Fact]
+        public void DismPackageNotApplicableExceptionTest()
+        {
+            Exception exception = DismException.GetDismExceptionForHResult(unchecked((int)DismApi.CBS_E_NOT_APPLICABLE));
+
+            exception.ShouldBeOfType<DismPackageNotApplicableException>();
+
+            exception.Message.ShouldBe(Resources.DismExceptionMessagePackageNotApplicable);
+        }
+
         [Fact]
         public void DismRebootRequiredExceptionTest()
         {

src/Microsoft.Dism/DismApi.AddPackage.cs

@@ -19,6 +19,7 @@ public static partial class DismApi
         /// <param name="preventPending">Specifies whether to add a package if it has pending online actions.</param>
         /// <exception cref="DismException">When a failure occurs.</exception>
         /// <exception cref="DismRebootRequiredException">When the operation requires a reboot to complete.</exception>
+        /// <exception cref="DismPackageNotApplicableException">When the package is not applicable to the specified session.</exception>
         public static void AddPackage(DismSession session, string packagePath, bool ignoreCheck, bool preventPending)
         {
             AddPackage(session, packagePath, ignoreCheck, preventPending, null);
@@ -35,6 +36,7 @@ public static void AddPackage(DismSession session, string packagePath, bool igno
         /// <exception cref="DismException">When a failure occurs.</exception>
         /// <exception cref="OperationCanceledException">When the user requested the operation be canceled.</exception>
         /// <exception cref="DismRebootRequiredException">When the operation requires a reboot to complete.</exception>
+        /// <exception cref="DismPackageNotApplicableException">When the package is not applicable to the specified session.</exception>
         public static void AddPackage(DismSession session, string packagePath, bool ignoreCheck, bool preventPending, Microsoft.Dism.DismProgressCallback progressCallback)
         {
             AddPackage(session, packagePath, ignoreCheck, preventPending, progressCallback, null);
@@ -52,6 +54,7 @@ public static void AddPackage(DismSession session, string packagePath, bool igno
         /// <exception cref="DismException">When a failure occurs.</exception>
         /// <exception cref="OperationCanceledException">When the user requested the operation be canceled.</exception>
         /// <exception cref="DismRebootRequiredException">When the operation requires a reboot to complete.</exception>
+        /// <exception cref="DismPackageNotApplicableException">When the package is not applicable to the specified session.</exception>
         public static void AddPackage(DismSession session, string packagePath, bool ignoreCheck, bool preventPending, Microsoft.Dism.DismProgressCallback progressCallback, object userData)
         {
             // Create a DismProgress object to wrap the callback and allow cancellation

src/Microsoft.Dism/DismException.cs

@@ -99,6 +99,9 @@ internal static Exception GetDismExceptionForHResult(int errorCode)
                 case DismApi.DISMAPI_E_OPEN_SESSION_HANDLES:
                     // User has not called CloseSession() on open sessions
                     return new DismOpenSessionsException(errorCode);
+
+                case DismApi.CBS_E_NOT_APPLICABLE:
+                    return new DismPackageNotApplicableException(errorCode);
             }
 
             // Attempt to get an error message from the DismApi
@@ -212,6 +215,49 @@ private DismOpenSessionsException(SerializationInfo serializationInfo, Streaming
         }
     }
 
+    /// <summary>
+    /// The exception that is thrown when a package is not applicable to a particular session.
+    /// </summary>
+    [Serializable]
+    public sealed class DismPackageNotApplicableException : DismException
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DismPackageNotApplicableException"/> class.
+        /// </summary>
+        /// <param name="errorCode">The error code to associate with the exception.</param>
+        public DismPackageNotApplicableException(int errorCode)
+        : base(errorCode, Resources.DismExceptionMessagePackageNotApplicable)
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DismPackageNotApplicableException"/> class.
+        /// </summary>
+        public DismPackageNotApplicableException()
+            : base()
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DismPackageNotApplicableException"/> class.
+        /// </summary>
+        /// <param name="message">The message that describes the error. </param>
+        public DismPackageNotApplicableException(string message)
+            : base(message)
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DismPackageNotApplicableException"/> class.
+        /// </summary>
+        /// <param name="message">The message that describes the error. </param>
+        /// <param name="innerException">The exception that is the cause of the current exception, or a null reference (<see langword="Nothing" /> in Visual Basic) if no inner exception is specified. </param>
+        public DismPackageNotApplicableException(string message, Exception innerException)
+            : base(message, innerException)
+        {
+        }
+    }
+
     /// <summary>
     /// The exception that is thrown when the previous operations requires a reboot.
     /// </summary>

src/Microsoft.Dism/NativeConstants.cs

@@ -182,6 +182,11 @@ public static partial class DismApi
         /// The requested operation is successful. The DISM session needs to be reloaded.
         /// </summary>
         internal const int DISMAPI_S_RELOAD_IMAGE_SESSION_REQUIRED = 0x00000001;  // 1
+
+        /// <summary>
+        /// The specified package is not applicable.
+        /// </summary>
+        internal const uint CBS_E_NOT_APPLICABLE = 0x800F081E;
 #pragma warning restore SA1310 // Field names must not contain underscore
     }
 }

src/Microsoft.Dism/Properties/Resources.resx

@@ -125,6 +125,10 @@
     <value>There are one or more open sessions.</value>
     <comment>Exception message when there are one or more open sessions and a user calls the Shutdown() method.</comment>
   </data>
+  <data name="DismExceptionMessagePackageNotApplicable" xml:space="preserve">
+    <value>The specified package is not applicable.</value>
+    <comment>Exception message when a package is not applicable.</comment>
+  </data>
   <data name="DismExceptionMessageRebootRequired" xml:space="preserve">
     <value>A restart is required to complete the operation.</value>
     <comment>Exception message when an operation requires a reboot.</comment>