update non-json serialization types (dotnet#8638)

Author: gewarren

xml/System.Runtime.Serialization/ISerializable.xml

@@ -50,12 +50,12 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>Allows an object to control its own serialization and deserialization.</summary>
+    <summary>Allows an object to control its own serialization and deserialization through binary and XML serialization.</summary>
     <remarks>
       <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
- Any class that might be serialized must be marked with the <xref:System.SerializableAttribute>. If a class needs to control its serialization process, it can implement the <xref:System.Runtime.Serialization.ISerializable> interface. The <xref:System.Runtime.Serialization.Formatter> calls the <xref:System.Runtime.Serialization.ISerializable.GetObjectData%2A> at serialization time and populates the supplied <xref:System.Runtime.Serialization.SerializationInfo> with all the data required to represent the object. The <xref:System.Runtime.Serialization.Formatter> creates a <xref:System.Runtime.Serialization.SerializationInfo> with the type of the object in the graph. Objects that need to send proxies for themselves can use the <xref:System.Runtime.Serialization.SerializationInfo.FullTypeName%2A> and <xref:System.Runtime.Serialization.SerializationInfo.AssemblyName%2A> methods on <xref:System.Runtime.Serialization.SerializationInfo> to change the transmitted information.  
+ Any class that might be serialized using binary or XML serialization must be marked with the <xref:System.SerializableAttribute>. If a class needs to control its binary or XML serialization process, it can implement the <xref:System.Runtime.Serialization.ISerializable> interface. The <xref:System.Runtime.Serialization.Formatter> calls the <xref:System.Runtime.Serialization.ISerializable.GetObjectData%2A> at serialization time and populates the supplied <xref:System.Runtime.Serialization.SerializationInfo> with all the data required to represent the object. The <xref:System.Runtime.Serialization.Formatter> creates a <xref:System.Runtime.Serialization.SerializationInfo> with the type of the object in the graph. Objects that need to send proxies for themselves can use the <xref:System.Runtime.Serialization.SerializationInfo.FullTypeName%2A> and <xref:System.Runtime.Serialization.SerializationInfo.AssemblyName%2A> methods on <xref:System.Runtime.Serialization.SerializationInfo> to change the transmitted information.  
   
  In the case of class inheritance, it is possible to serialize a class that derives from a base class that implements <xref:System.Runtime.Serialization.ISerializable>. In this case, the derived class should call the base class implementation of <xref:System.Runtime.Serialization.ISerializable.GetObjectData%2A> inside its implementation of <xref:System.Runtime.Serialization.ISerializable.GetObjectData%2A>. Otherwise, the data from the base class will not be serialized.  
   
@@ -69,12 +69,13 @@
   
  As a general design pattern, it would be unusual for a class to be both marked with the serializable attribute and extend <xref:System.MarshalByRefObject>. Developers should think carefully about the possible serialization and remoting scenarios when combining these two characteristics. One example where this might be applicable is with a <xref:System.IO.MemoryStream>. While the base class of <xref:System.IO.MemoryStream> (<xref:System.IO.Stream>) extends from <xref:System.MarshalByRefObject>, it is possible to capture the state of a <xref:System.IO.MemoryStream> and restore it at will. It might, therefore, be meaningful to serialize the state of this stream into a database and restore it at some later point in time. However, when used through remoting, an object of this type would be proxied.  
   
- For more information about serialization of classes that extend <xref:System.MarshalByRefObject>, see <xref:System.Runtime.Remoting.Messaging.RemotingSurrogateSelector>. For more information about implementing <xref:System.Runtime.Serialization.ISerializable>, see [Custom Serialization](/dotnet/standard/serialization/custom-serialization).  
-  
-   
+ For more information about serialization of classes that extend <xref:System.MarshalByRefObject>, see <xref:System.Runtime.Remoting.Messaging.RemotingSurrogateSelector>. For more information about implementing <xref:System.Runtime.Serialization.ISerializable>, see [Custom Serialization](/dotnet/standard/serialization/custom-serialization).
+
+> [!NOTE]
+> This interface does not apply to JSON serialization using <xref:System.Text.Json?displayProperty=fullName>.
   
 ## Examples  
- The following code example demonstrates the use of the <xref:System.Runtime.Serialization.ISerializable> interface to define custom serialization behavior for a class.  
+ The following code example demonstrates the use of the <xref:System.Runtime.Serialization.ISerializable> interface to define custom binary serialization behavior for a class.  
   
  :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/ISerializable Interface Example/CPP/iobjectreference.cpp" id="Snippet1":::
  :::code language="csharp" source="~/snippets/csharp/System.Runtime.Serialization/ISerializable/Overview/iobjectreference.cs" id="Snippet1":::

xml/System/NonSerializedAttribute.xml

@@ -79,15 +79,16 @@ public event ChangedEventHandler Changed;
   
  If a field is not serialized, but it still requires a default value that must be supplied after deserialization, you can create a method that supplies the field with a value, then apply the <xref:System.Runtime.Serialization.OnDeserializedAttribute> to the method.  
   
- For more information about using attributes, see [Attributes](/dotnet/standard/attributes/).  
-  
-   
+ For more information about using attributes, see [Attributes](/dotnet/standard/attributes/).
+
+> [!NOTE]
+> This attribute does not apply to JSON serialization using <xref:System.Text.Json?displayProperty=fullName>.
   
 ## Examples  
- The following example demonstrates serialization of an object marked with the <xref:System.SerializableAttribute> attribute, and the behavior of a field marked with the <xref:System.NonSerializedAttribute> in the serialized object.  
+ The following example demonstrates SOAP serialization of an object marked with the <xref:System.SerializableAttribute> attribute, and the behavior of a field marked with the <xref:System.NonSerializedAttribute> in the serialized object.  
   
 > [!NOTE]
->  The code uses the <xref:System.Runtime.Serialization.Formatters.Soap.SoapFormatter> class to serialize the object. The class is found in the system.runtime.serialization.formatters.soap.dll, which is not loaded by default into a project. To run the code, you must add a reference to the DLL to your project.  
+> The code uses the <xref:System.Runtime.Serialization.Formatters.Soap.SoapFormatter> class to serialize the object. The class is found in the system.runtime.serialization.formatters.soap.dll file, which is not loaded by default into a project. To run the code, you must add a reference to the DLL to your project.  
   
  :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/SerializationAttributes/CPP/s.cpp" id="Snippet1":::
  :::code language="csharp" source="~/snippets/csharp/System/NonSerializedAttribute/Overview/s.cs" id="Snippet1":::

xml/System/SerializableAttribute.xml

@@ -57,25 +57,26 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>Indicates that a class can be serialized. This class cannot be inherited.</summary>
+    <summary>Indicates that a class can be serialized using binary or XML serialization. This class cannot be inherited.</summary>
     <remarks>
       <format type="text/markdown"><![CDATA[  
   
 ## Remarks  
- Apply the <xref:System.SerializableAttribute> attribute to a type to indicate that instances of this type can be serialized. The common language runtime throws <xref:System.Runtime.Serialization.SerializationException> if any type in the graph of objects being serialized does not have the <xref:System.SerializableAttribute> attribute applied.  
+ Apply the <xref:System.SerializableAttribute> attribute to a type to indicate that instances of this type can be serialized using binary or XML serialization. The common language runtime throws <xref:System.Runtime.Serialization.SerializationException> if any type in the graph of objects being serialized does not have the <xref:System.SerializableAttribute> attribute applied.  
   
- Apply the <xref:System.SerializableAttribute> attribute even if the class also implements the <xref:System.Runtime.Serialization.ISerializable> interface to control the serialization process.  
+ Apply the <xref:System.SerializableAttribute> attribute even if the class also implements the <xref:System.Runtime.Serialization.ISerializable> interface to control the binary serialization process.  
   
- When you apply the <xref:System.SerializableAttribute> attribute to a type, all private and public fields are serialized by default. You can control serialization more granularly by implementing the <xref:System.Runtime.Serialization.ISerializable> interface to override the serialization process.  
+ When you apply the <xref:System.SerializableAttribute> attribute to a type, all private and public fields are serialized by default. You can control binary serialization more granularly by implementing the <xref:System.Runtime.Serialization.ISerializable> interface to override the serialization process.  
   
- Or you can exclude fields from serialization by applying the <xref:System.NonSerializedAttribute> attribute to the field. If a field of a serializable type contains a pointer, a handle, or some other data structure that is specific to a particular environment, and cannot be meaningfully reconstituted in a different environment, then you might want to apply the <xref:System.NonSerializedAttribute> attribute to that field.  
+ Or you can exclude fields from serialization by applying the <xref:System.NonSerializedAttribute> attribute to the field. If a field of a binary-serializable type contains a pointer, a handle, or some other data structure that is specific to a particular environment, and cannot be meaningfully reconstituted in a different environment, then you might want to apply the <xref:System.NonSerializedAttribute> attribute to that field.  
   
- For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). For more information about serialization, see <xref:System.Runtime.Serialization>.  
-  
-   
+ For more information about using attributes, see [Attributes](/dotnet/standard/attributes/). For more information about binary serialization, see <xref:System.Runtime.Serialization>.
+
+> [!NOTE]
+> This attribute does not apply to JSON serialization using <xref:System.Text.Json?displayProperty=fullName>.
   
 ## Examples  
- The following example demonstrates serialization of an object that is marked with the <xref:System.SerializableAttribute> attribute. To use the <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter> instead of the <xref:System.Runtime.Serialization.Formatters.Soap.SoapFormatter>, uncomment the appropriate lines.  
+ The following example demonstrates SOAP serialization of an object that's marked with the <xref:System.SerializableAttribute> attribute. To use the <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter> instead of the <xref:System.Runtime.Serialization.Formatters.Soap.SoapFormatter>, uncomment the appropriate lines.  
   
  :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/SerializationAttributes/CPP/s.cpp" id="Snippet1":::
  :::code language="csharp" source="~/snippets/csharp/System/NonSerializedAttribute/Overview/s.cs" id="Snippet1":::

xml/System/Type.xml

@@ -14587,21 +14587,19 @@ Byref-like structures are declared using `ref struct` keyword in C#. An instance
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets a value indicating whether the <see cref="T:System.Type" /> is serializable.</summary>
+        <summary>Gets a value indicating whether the <see cref="T:System.Type" /> is binary serializable.</summary>
         <value>
-          <see langword="true" /> if the <see cref="T:System.Type" /> is serializable; otherwise, <see langword="false" />.</value>
+          <see langword="true" /> if the <see cref="T:System.Type" /> is binary serializable; otherwise, <see langword="false" />.</value>
         <remarks>
           <format type="text/markdown"><![CDATA[  
 
 ## Remarks  
 
-Types that are defined in the .NET Standard are not marked with <xref:System.SerializableAttribute>. Instead, each .NET implementation determines whether a type is serializable. At run time, you can use the <xref:System.Type.IsSerializable%2A> property to determine whether that implementation supports serialization of an instance of the type. For more information and an example, see [How to determine if a .NET Standard object is serializable](/dotnet/standard/serialization/how-to-determine-if-netstandard-object-is-serializable).
+Types that are defined in the .NET Standard are not marked with <xref:System.SerializableAttribute>. Instead, each .NET implementation determines whether a type is binary serializable. At run time, you can use the <xref:System.Type.IsSerializable%2A> property to determine whether that implementation supports binary serialization of an instance of the type. For more information and an example, see [How to determine if a .NET Standard object is serializable](/dotnet/standard/serialization/how-to-determine-if-netstandard-object-is-serializable).
 
  If the current <xref:System.Type> represents a constructed generic type, this property applies to the generic type definition from which the type was constructed. For example, if the current <xref:System.Type> represents `MyGenericType<int>` (`MyGenericType(Of Integer)` in Visual Basic), the value of this property is determined by `MyGenericType<T>`.  
 
- If the current <xref:System.Type> represents a type parameter in the definition of a generic type or generic method, this property always returns `false`.  
-  
-   
+ If the current <xref:System.Type> represents a type parameter in the definition of a generic type or generic method, this property always returns `false`.
 
 ## Examples  
  The following example creates an instance of `MyTestClass` class, sets the [Serializable] attribute, and checks the `IsSerializable` property for `true` or `false`.