binary serialization updates (dotnet#2847)

* binary serialization updates

* removed links to deleted articles

* Update version-tolerant-serialization.md

Author: mairaw

.openpublishing.redirection.json

@@ -823,6 +823,14 @@
             "redirect_url": "/dotnet/standard/net-standard",
             "redirect_document_id": true
         },
+        {
+            "source_path": "docs/standard/serialization/marshal-by-value.md",
+            "redirect_url": "/dotnet/standard/serialization-concepts"
+        },
+        {
+            "source_path": "docs/standard/serialization/persistent-storage.md",
+            "redirect_url": "/dotnet/standard/serialization-concepts"
+        },
         {
             "source_path": "docs/tutorials/getting-started-with-csharp/microservices.md",
             "redirect_url": "/dotnet/csharp/tutorials/microservices"

docs/standard/serialization/basic-serialization.md

@@ -1,27 +1,23 @@
 ---
-title: "Basic Serialization"
-ms.custom: ""
+title: "Basic serialization"
 ms.date: "03/30/2017"
 ms.prod: ".net"
-ms.reviewer: ""
-ms.suite: ""
-ms.tgt_pltfrm: ""
 ms.topic: "article"
-dev_langs: 
-  - "VB"
-  - "CSharp"
-  - "C++"
-  - "jsharp"
 helpviewer_keywords: 
   - "binary serialization, basic serialization"
   - "serialization, basic serialization"
 ms.assetid: d899d43c-335a-433e-a589-cd187192984f
+dev_langs: 
+  - "CSharp"
 caps.latest.revision: 7
 author: "Erikre"
 ms.author: "erikre"
 manager: "erikre"
 ---
-# Basic Serialization
+# Basic serialization
+
+[!INCLUDE [binary-serialization-warning](../../../includes/binary-serialization-warning.md)]
+
 The easiest way to make a class serializable is to mark it with the <xref:System.SerializableAttribute> as follows.  
 
 ```csharp  
@@ -33,7 +29,7 @@ public class MyObject {
 }  
 ```  
 
- The code example below shows how an instance of this class can be serialized to a file.  
+The following code example shows how an instance of this class can be serialized to a file.  
 
 ```csharp  
 MyObject obj = new MyObject();  
@@ -46,9 +42,9 @@ formatter.Serialize(stream, obj);
 stream.Close();  
 ```  
 
- This example uses a binary formatter to do the serialization. All you need to do is create an instance of the stream and the formatter you intend to use, and then call the **Serialize** method on the formatter. The stream and the object to serialize are provided as parameters to this call. Although it is not explicitly demonstrated in this example, all member variables of a class will be serialized—even variables marked as private. In this aspect, binary serialization differs from the <xref:System.Xml.Serialization.XmlSerializer> class, which only serializes public fields. For information on excluding member variables from binary serialization, see [Selective Serialization](../../../docs/standard/serialization/selective-serialization.md).  
+This example uses a binary formatter to do the serialization. All you need to do is create an instance of the stream and the formatter you intend to use, and then call the **Serialize** method on the formatter. The stream and the object to serialize are provided as parameters to this call. Although it is not explicitly demonstrated in this example, all member variables of a class will be serialized—even variables marked as private. In this aspect, binary serialization differs from the <xref:System.Xml.Serialization.XmlSerializer> class, which only serializes public fields. For information on excluding member variables from binary serialization, see [Selective Serialization](selective-serialization.md).  
 
- Restoring the object back to its former state is just as easy. First, create a stream for reading and a <xref:System.Runtime.Serialization.Formatter>, and then instruct the formatter to deserialize the object. The code example below shows how this is done.  
+Restoring the object back to its former state is just as easy. First, create a stream for reading and a <xref:System.Runtime.Serialization.Formatter>, and then instruct the formatter to deserialize the object. The code example below shows how this is done.  
 
 ```csharp  
 IFormatter formatter = new BinaryFormatter();  
@@ -62,9 +58,9 @@ Console.WriteLine("n2: {0}", obj.n2);
 Console.WriteLine("str: {0}", obj.str);  
 ```  
 
- The <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter> used above is very efficient and produces a compact byte stream. All objects serialized with this formatter can also be deserialized with it, which makes it an ideal tool for serializing objects that will be deserialized on the .NET Framework. It is important to note that constructors are not called when an object is deserialized. This constraint is placed on deserialization for performance reasons. However, this violates some of the usual contracts the runtime makes with the object writer, and developers should ensure that they understand the ramifications when marking an object as serializable.  
+The <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter> used above is very efficient and produces a compact byte stream. All objects serialized with this formatter can also be deserialized with it, which makes it an ideal tool for serializing objects that will be deserialized on the .NET Framework. It is important to note that constructors are not called when an object is deserialized. This constraint is placed on deserialization for performance reasons. However, this violates some of the usual contracts the runtime makes with the object writer, and developers should ensure that they understand the ramifications when marking an object as serializable.  
 
- If portability is a requirement, use the <xref:System.Runtime.Serialization.Formatters.Soap.SoapFormatter> instead. Simply replace the **BinaryFormatter** in the code above with **SoapFormatter,** and call **Serialize** and **Deserialize** as before. This formatter produces the following output for the example used above.  
+If portability is a requirement, use the <xref:System.Runtime.Serialization.Formatters.Soap.SoapFormatter> instead. Simply replace the **BinaryFormatter** in the code above with **SoapFormatter,** and call **Serialize** and **Deserialize** as before. This formatter produces the following output for the example used above.  
 
 ```xml  
 <SOAP-ENV:Envelope  
@@ -87,7 +83,7 @@ Console.WriteLine("str: {0}", obj.str);
 </SOAP-ENV:Envelope>  
 ```  
 
- It is important to note that the **Serializable** attribute cannot be inherited. If you derive a new class from `MyObject`, the new class must be marked with the attribute as well, or it cannot be serialized. For example, when you attempt to serialize an instance of the class below, you will get a <xref:System.Runtime.Serialization.SerializationException> informing you that the `MyStuff` type is not marked as serializable.  
+It's important to note that the [Serializable](xref:System.SerializableAttribute) attribute cannot be inherited. If you derive a new class from `MyObject`, the new class must be marked with the attribute as well, or it cannot be serialized. For example, when you attempt to serialize an instance of the class below, you'll get a <xref:System.Runtime.Serialization.SerializationException> informing you that the `MyStuff` type is not marked as serializable.  
 
 ```csharp  
 public class MyStuff : MyObject   
@@ -96,8 +92,8 @@ public class MyStuff : MyObject
 }  
 ```  
 
- Using the **Serializable** attribute is convenient, but it has limitations as demonstrated above. Refer to the [Serialization Guidelines](../../../docs/standard/serialization/serialization-guidelines.md) for information about when you should mark a class for serialization; serialization cannot be added to a class after it has been compiled.  
+ Using the [Serializable](xref:System.SerializableAttribute) attribute is convenient, but it has limitations as previously demonstrated. Refer to the [Serialization Guidelines](serialization-guidelines.md) for information about when you should mark a class for serialization. Serialization cannot be added to a class after it has been compiled.  
 
-## See Also  
- [Binary Serialization](../../../docs/standard/serialization/binary-serialization.md)   
- [XML and SOAP Serialization](../../../docs/standard/serialization/xml-and-soap-serialization.md)
+## See also  
+ [Binary Serialization](binary-serialization.md)   
+ [XML and SOAP Serialization](xml-and-soap-serialization.md)

docs/standard/serialization/binary-serialization.md

@@ -1,17 +1,8 @@
 ---
-title: "Binary Serialization"
-ms.custom: ""
-ms.date: "03/30/2017"
+title: "Binary serialization"
+ms.date: "08/07/2017"
 ms.prod: ".net"
-ms.reviewer: ""
-ms.suite: ""
-ms.tgt_pltfrm: ""
 ms.topic: "article"
-dev_langs: 
-  - "VB"
-  - "CSharp"
-  - "C++"
-  - "jsharp"
 helpviewer_keywords: 
   - "binary serialization"
   - "serialization, about serialization"
@@ -23,15 +14,17 @@ author: "Erikre"
 ms.author: "erikre"
 manager: "erikre"
 ---
-# Binary Serialization
-Serialization can be defined as the process of storing the state of an object to a storage medium. During this process, the public and private fields of the object and the name of the class, including the assembly containing the class, are converted to a stream of bytes, which is then written to a data stream. When the object is subsequently deserialized, an exact clone of the original object is created.  
-  
- When implementing a serialization mechanism in an object-oriented environment, you have to make a number of tradeoffs between ease of use and flexibility. The process can be automated to a large extent, provided you are given sufficient control over the process. For example, situations may arise where simple binary serialization is not sufficient, or there might be a specific reason to decide which fields in a class need to be serialized. The following sections examine the robust serialization mechanism provided with the .NET Framework and highlight a number of important features that allow you to customize the process to meet your needs.  
+# Binary serialization
+Serialization can be defined as the process of storing the state of an object to a storage medium. During this process, the public and private fields of the object and the name of the class, including the assembly containing the class, are converted to a stream of bytes, which is then written to a data stream. When the object is subsequently deserialized, an exact clone of the original object is created.
+
+When implementing a serialization mechanism in an object-oriented environment, you have to make a number of tradeoffs between ease of use and flexibility. The process can be automated to a large extent, provided you are given sufficient control over the process. For example, situations may arise where simple binary serialization is not sufficient, or there might be a specific reason to decide which fields in a class need to be serialized. The following sections examine the robust serialization mechanism provided with .NET and highlight a number of important features that allow you to customize the process to meet your needs.
 
 > [!NOTE]
->  The state of a UTF-8 or UTF-7 encoded object is not preserved if the object is serialized and deserialized using different .NET Framework versions.  
+>  The state of a UTF-8 or UTF-7 encoded object is not preserved if the object is serialized and deserialized using different .NET Framework versions.
+
+[!INCLUDE [binary-serialization-warning](../../../includes/binary-serialization-warning.md)]
 
-## In This Section  
+## In this section  
  [Serialization Concepts](../../../docs/standard/serialization/serialization-concepts.md)  
  Discusses two scenarios where serialization is useful: when persisting data to storage and when passing objects across application domains.  
 
@@ -57,7 +50,7 @@ Serialization can be defined as the process of storing the state of an object to
  <xref:System.Runtime.Serialization>  
  Contains classes that can be used for serializing and deserializing objects.  
 
-## Related Sections  
+## Related sections  
  [XML and SOAP Serialization](../../../docs/standard/serialization/xml-and-soap-serialization.md)  
  Describes the XML serialization mechanism that is included with the common language runtime.