Mark CriteriaBase as obsolete (#4467)

* #3785 Update samples for rc4 * #3785 Update samples for rc4 * #3785 Update samples for rc4 * #3785 Update samples for rc4 * #4462 Mark CriteriaBase as obsolete * #4462 Enhance docs around CriteriaBase and serialization of types --------- Co-authored-by: Stefan Ossendorf <StefanOssendorf@users.noreply.github.com>
MarimerLLC · Feb 6, 2025 · 1b7e36b · 1b7e36b
1 parent 07e9258
commit 1b7e36b
Show file tree

Hide file tree

Showing 16 changed files with 63 additions and 16 deletions.
diff --git a/Source/Csla.test/Basic/GenRootBase.cs b/Source/Csla.test/Basic/GenRootBase.cs
@@ -32,7 +32,7 @@ public string Data
     }
 
     [Serializable]
-    internal class Criteria : CriteriaBase<Criteria>
+    internal class Criteria : ReadOnlyBase<Criteria>
     {
       public string _data;
 

diff --git a/Source/Csla.test/DataPortal/DpRoot.cs b/Source/Csla.test/DataPortal/DpRoot.cs
@@ -40,7 +40,7 @@ public string Auth
     #region "Criteria class"
 
     [Serializable]
-    internal class Criteria : CriteriaBase<Criteria>
+    internal class Criteria : ReadOnlyBase<Criteria>
     {
       public static PropertyInfo<string> DataProperty = RegisterProperty<string>(c => c.Data);
       public string Data

diff --git a/Source/Csla.test/DataPortal/LegacySplitBase.cs b/Source/Csla.test/DataPortal/LegacySplitBase.cs
@@ -27,7 +27,7 @@ public int Id
     #region Data Access
 
     [Serializable]
-    internal class Criteria : CriteriaBase<Criteria>
+    internal class Criteria : ReadOnlyBase<Criteria>
     {
       public int Id { get; }
 

diff --git a/Source/Csla.test/DataPortal/SplitBase.cs b/Source/Csla.test/DataPortal/SplitBase.cs
@@ -47,7 +47,7 @@ public static void DeleteObject(int id, IDataPortal<T> dataPortal)
     #region Data Access
 
     [Serializable]
-    private class Criteria : CriteriaBase<Criteria>
+    private class Criteria : ReadOnlyBase<Criteria>
     {
       public int Id { get; }
 

diff --git a/Source/Csla.test/DataPortal/SplitOverloadBase.cs b/Source/Csla.test/DataPortal/SplitOverloadBase.cs
@@ -50,15 +50,15 @@ public static void DeleteObject(int id, IDataPortal<T> dataPortal)
     #region Data Access
 
     [Serializable]
-    private class Criteria : CriteriaBase<Criteria>
+    private class Criteria : ReadOnlyBase<Criteria>
     {
       public int Id { get; }
 
       public Criteria(int id)
       { Id = id; }
     }
     [Serializable]
-    private class Criteria1 : CriteriaBase<Criteria1>
+    private class Criteria1 : ReadOnlyBase<Criteria1>
     {
       public int Id { get; }
 

diff --git a/Source/Csla.test/Fakes/Server/CslaDataProvider/Customer.cs b/Source/Csla.test/Fakes/Server/CslaDataProvider/Customer.cs
@@ -172,7 +172,7 @@ protected override void AddBusinessRules()
 
 
     [Serializable]
-    public class FetchCriteria : CriteriaBase<FetchCriteria>
+    public class FetchCriteria : ReadOnlyBase<FetchCriteria>
     {
       public FetchCriteria() { }
 

diff --git a/Source/Csla.test/Fakes/Server/CslaDataProvider/CustomerWithError.cs b/Source/Csla.test/Fakes/Server/CslaDataProvider/CustomerWithError.cs
@@ -85,7 +85,7 @@ protected override void AddBusinessRules()
 
 
     [Serializable]
-    public class FetchCriteria : CriteriaBase<FetchCriteria>
+    public class FetchCriteria : ReadOnlyBase<FetchCriteria>
     {
       public FetchCriteria() { }
 

diff --git a/Source/Csla.test/RollBack/RollbackRoot.cs b/Source/Csla.test/RollBack/RollbackRoot.cs
@@ -32,7 +32,7 @@ public bool Fail
     }
 
     [Serializable]
-    protected class Criteria : CriteriaBase<Criteria>
+    protected class Criteria : ReadOnlyBase<Criteria>
     {
       private static PropertyInfo<string> DataProperty = RegisterProperty<string>(nameof(Data));
 

diff --git a/Source/Csla.test/ValidationRules/HasRulesManager.cs b/Source/Csla.test/ValidationRules/HasRulesManager.cs
@@ -28,7 +28,7 @@ protected override void AddBusinessRules()
     }
 
     [Serializable]
-    public class Criteria : CriteriaBase<Criteria>
+    public class Criteria : ReadOnlyBase<Criteria>
     {
       public string _name;
 

diff --git a/Source/Csla.test/ValidationRules/HasRulesManager2.cs b/Source/Csla.test/ValidationRules/HasRulesManager2.cs
@@ -28,7 +28,7 @@ protected override void AddBusinessRules()
     }
 
     [Serializable]
-    public class Criteria : CriteriaBase<Criteria>
+    public class Criteria : ReadOnlyBase<Criteria>
     {
       public string _name;
 

diff --git a/Source/Csla/CriteriaBase.cs b/Source/Csla/CriteriaBase.cs
@@ -19,6 +19,7 @@ namespace Csla
   /// derived in a business class. 
   /// </summary>
   [Serializable]
+  [Obsolete("Use types that can be serialized by CSLA. See the `/docs/Upgrade to CSLA 9.md` document for details.", false)]
   public abstract class CriteriaBase<
 #if NET8_0_OR_GREATER
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)]

diff --git a/Source/Csla/Security/UsernameCriteria.cs b/Source/Csla/Security/UsernameCriteria.cs
@@ -16,7 +16,7 @@ namespace Csla.Security
   /// custom identity class.
   /// </summary>
   [Serializable]
-  public class UsernameCriteria : CriteriaBase<UsernameCriteria>
+  public class UsernameCriteria : ReadOnlyBase<UsernameCriteria>
   {
     /// <summary>
     /// Username property definition.

diff --git a/Source/csla.netcore.test/Basic/GenRootBase.cs b/Source/csla.netcore.test/Basic/GenRootBase.cs
@@ -32,7 +32,7 @@ public string Data
     }
 
     [Serializable]
-    public class Criteria : CriteriaBase<Criteria>
+    public class Criteria : ReadOnlyBase<Criteria>
     {
       public string _data;
 

diff --git a/Source/csla.netcore.test/DataPortal/InheritedOperationTests.cs b/Source/csla.netcore.test/DataPortal/InheritedOperationTests.cs
@@ -60,7 +60,7 @@ private void DataPortal_Fetch(Criteria criteria)
     }
 
     [Serializable]
-    public class Criteria : CriteriaBase<Criteria>;
+    public class Criteria : ReadOnlyBase<Criteria>;
   }
 
   [Serializable]

diff --git a/docs/Upgrading to CSLA 9.md b/docs/Upgrading to CSLA 9.md
@@ -90,6 +90,14 @@ CSLA 9 fixes the issue with transfering binary data between the client and serve
         .UseHttpProxy(o => o.DataPortalUrl = "https://server/api/DataPortal"))));
 ```
 
+## CriteriaBase Obsolete
+
+The `CriteriaBase` class is now obsolete. You should use [CSLA serializable](serialization.md) types for criteria values instead.
+
+In most cases you can simply pass your criteria values to a data portal method as parameters, and CSLA will serialize them for you. There is no longer the need for a complex type to contain the parameter values.
+
+If you want to use a complex type to contain the parameter values, thus passing a single "criteria" value to the data portal you should consider replacing `CriteriaBase` with `ReadOnlyBase`. This is because criteria classes are typically read-only, and `ReadOnlyBase` provides the necessary functionality.
+
 ## BinaryFormatter and NetDataContractSerializer Removed
 
 CSLA 9 removes support for the `BinaryFormatter` serialization format. This format is not secure and should not be used.

diff --git a/docs/serialization.md b/docs/serialization.md
@@ -4,12 +4,50 @@ Serialization is the process of taking the state of an object graph and converti
 
 CSLA .NET relies on deep serialization to do this work. Most serializers do shallow serialization: operating only on public properties. Deep serialization serializes at the field level, including non-public field values. Deep serialization also preserves the shape of the object graph upon deserialization, where shallow serialization usually changes the shape of the object graph on deserialization, often creating new instances of objects that didn't exist in the original graph.
 
+## CSLA 9+
+
+The default serializer for CSLA (version 6 and later) is `MobileFormatter`. This is a custom serializer that is optimized for CSLA .NET, and is the only serializer that is guaranteed to work on all .NET implementations.
+
+### Using MobileFormatter
+
+MobileFormatter supports many basic .NET types, including "primitive" types like `int`, `string`, `DateTime`, etc. It also supports `List<T>`, `Dictionary<K,V>`, and other common collection types. It also supports any type that implements `IMobileObject`, which includes all CSLA base types.
+
+If you create your complex types by subclassing CSLA base types and using the managed property syntax, you don't need to do anything special to support serialization. 
+
+You can also serialize your own types that don't subclass from CSLA. In this case your type needs to implement `IMobileObject` and manage the serialization of your type's state, or create and register a custom serializer for your type.
+
+### Custom Serializers
+
+Starting with CSLA 9 it is possible to create your own custom serializers for specific types. On application startup you register your custom serializer with CSLA and the MobileFormatter will use your custom serializer for the specific type(s) you've registered.
+
+CSLA includes some pre-built serializers in the [/Source/Csla/Serialization](https://github.com/MarimerLLC/csla/tree/main/Source/Csla/Serialization/Mobile/CustomSerializers) folder. The `ClaimsPrincipalSerializer` is registered by default, and you can register the `PocoSerializer` to serialize POCO types if you choose.
+
+### Replacing MobileFormatter
+
+It is possible to create your own equivalent to `MobileFormatter`, but this is a complex and error-prone task.
+
+There are already some serializers you may consider using.
+
+#### AutoSerialization
+
+The CSLA project includes an optional NuGet package that brings in a code generator to optimize the use of `MobileFormatter`. This package is called `Csla.AutoSerialization` and is available on NuGet.
+
+The code and readme for [AutoSerialization](https://github.com/MarimerLLC/csla/tree/main/Source/Csla.Generators/cs/AutoSerialization) are in the CSLA project.
+
+#### CslaGeneratorSerialization
+
+@JasonBock has created a serializer for CSLA 9 that may provide some insights: [CslaGeneratorSerialization](https://github.com/JasonBock/CslaGeneratorSerialization).
+
+Jason's serializer offers substantial performance and memory consumption benefits over `MobileFormatter`.
+
+## History
+
 Prior to .NET 9, .NET provided two built-in deep serializers:
 
 * `BinaryFormatter`
 * `NetDataContractSerializer` (NDCS)
 
-CSLA .NET provides its own highly optimized serializer:
+CSLA .NET provides its own serializer:
 
 * `MobileFormatter`
 
@@ -25,7 +63,7 @@ In CSLA 6 the default serializer is `MobileFormatter`. In previous versions, the
 * .NET Core defaults to `MobileFormatter`
 * Mono (Xamarin/WebAssembly) defaults to `MobileFormatter`
 
-## MobileFormatter Constraints
+### MobileFormatter Constraints
 
 The `MobileFormatter` imposes some constraints on your code beyond `BinaryFormatter` or NDCS. These constraints are why `MobileFormatter` works on all .NET implementations and why we've been able to optimize it for CSLA .NET.