327 строки
13 KiB
XML
327 строки
13 KiB
XML
<?xml version="1.0"?>
|
|
<doc>
|
|
<assembly>
|
|
<name>Gendarme.Rules.Serialization</name>
|
|
</assembly>
|
|
<members>
|
|
<member name="T:Gendarme.Rules.Serialization.CallBaseMethodsOnISerializableTypesRule">
|
|
<summary>
|
|
This rule checks types that implement the <c>System.ISerializable</c> interface
|
|
and fires if either the serialization constructor or the <c>GetObjectData</c>
|
|
method does not call it's <c>base</c> type, potentially breaking the serialization
|
|
process.
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
[Serializable]
|
|
public class Base : ISerializable {
|
|
// ...
|
|
}
|
|
[Serializable]
|
|
public class Bad : Base {
|
|
int value;
|
|
protected BadDerived (SerializationInfo info, StreamingContext context)
|
|
{
|
|
value = info.GetInt32 ("value");
|
|
}
|
|
public override void GetObjectData (SerializationInfo info, StreamingContext context)
|
|
{
|
|
info.AddValue ("value", value);
|
|
}
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example:
|
|
<code>
|
|
[Serializable]
|
|
public class Base : ISerializable {
|
|
// ...
|
|
}
|
|
[Serializable]
|
|
public class Good : Base {
|
|
int value;
|
|
protected BadDerived (SerializationInfo info, StreamingContext context) : base (info, context)
|
|
{
|
|
value = info.GetInt32 ("value");
|
|
}
|
|
public override void GetObjectData (SerializationInfo info, StreamingContext context)
|
|
{
|
|
info.AddValue ("value", value);
|
|
base.GetObjectData (info, context);
|
|
}
|
|
}
|
|
</code></example>
|
|
<remarks>This rule is available since Gendarme 2.2</remarks>
|
|
</member>
|
|
<member name="T:Gendarme.Rules.Serialization.DeserializeOptionalFieldRule">
|
|
<summary>
|
|
This rule will fire if a type has fields marked with <c>[OptionalField]</c>, but does
|
|
not have methods decorated with the <c>[OnDeserialized]</c> or <c>[OnDeserializing]</c>
|
|
attributes. This is a problem because the binary deserializer does not actually construct
|
|
objects (it uses <c>System.Runtime.Serialization.FormatterServices.GetUninitializedObject</c>
|
|
instead). So, if binary deserialization is used the optional field(s) will be zeroed instead
|
|
of properly initialized.
|
|
This rule only applies to assemblies compiled with the .NET framework version 2.0
|
|
(or later).
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
[Serializable]
|
|
public class ClassWithOptionalField {
|
|
[OptionalField]
|
|
private int optional;
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example:
|
|
<code>
|
|
[Serializable]
|
|
public class ClassWithOptionalField {
|
|
// Normally the (compiler generated) default constructor will
|
|
// initialize this. The default constructor will be called by the
|
|
// XML and Soap deserializers, but not the binary serializer.
|
|
[OptionalField]
|
|
private int optional = 1;
|
|
// This will be called immediately after the object is
|
|
// deserialized.
|
|
[OnDeserializing]
|
|
private void OnDeserializing (StreamingContext context)
|
|
{
|
|
optional = 1;
|
|
}
|
|
}
|
|
</code></example>
|
|
<remarks>This rule is available since Gendarme 2.0</remarks>
|
|
</member>
|
|
<member name="T:Gendarme.Rules.Serialization.ImplementISerializableCorrectlyRule">
|
|
<summary>
|
|
This rule checks for types that implement <c>ISerializable</c>. Such types
|
|
serialize their data by implementing <c>GetObjectData</c>. This
|
|
rule verifies that every instance field, not decorated with the <c>[NonSerialized]</c>
|
|
attribute is serialized by the <c>GetObjectData</c> method. This rule will also warn
|
|
if the type is unsealed and the <c>GetObjectData</c> is not <c>virtual</c>.
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
[Serializable]
|
|
public class Bad : ISerializable {
|
|
int foo;
|
|
string bar;
|
|
protected Bad (SerializationInfo info, StreamingContext context)
|
|
{
|
|
foo = info.GetInt32 ("foo");
|
|
}
|
|
// extensibility is limited since GetObjectData is not virtual:
|
|
// any type inheriting won't be able to serialized additional fields
|
|
public void GetObjectData (SerializationInfo info, StreamingContext context)
|
|
{
|
|
info.AddValue ("foo", foo);
|
|
// 'bar' is not serialized, if not needed then the field should
|
|
// be decorated with [NotSerialized]
|
|
}
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example (virtual and not serialized):
|
|
<code>
|
|
[Serializable]
|
|
public class Good : ISerializable {
|
|
int foo;
|
|
[NotSerialized]
|
|
string bar;
|
|
protected Good (SerializationInfo info, StreamingContext context)
|
|
{
|
|
foo = info.GetInt32 ("foo");
|
|
}
|
|
public virtual void GetObjectData (SerializationInfo info, StreamingContext context)
|
|
{
|
|
info.AddValue ("foo", foo);
|
|
}
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example (sealed type and serialized):
|
|
<code>
|
|
[Serializable]
|
|
public sealed class Good : ISerializable {
|
|
int foo;
|
|
string bar;
|
|
protected Good (SerializationInfo info, StreamingContext context)
|
|
{
|
|
foo = info.GetInt32 ("foo");
|
|
}
|
|
public void GetObjectData (SerializationInfo info, StreamingContext context)
|
|
{
|
|
info.AddValue ("foo", foo);
|
|
info.AddValue ("bar", bar);
|
|
}
|
|
}
|
|
</code></example>
|
|
<remarks>This rule is available since Gendarme 2.0</remarks>
|
|
</member>
|
|
<member name="T:Gendarme.Rules.Serialization.MarkAllNonSerializableFieldsRule">
|
|
<summary>
|
|
This rule checks for serializable types, i.e. decorated with the <c>[Serializable]</c>
|
|
attribute, and checks to see if all its fields are serializable as well. If not the rule will
|
|
fire unless the field is decorated with the <c>[NonSerialized]</c> attribute.
|
|
The rule will also warn if the field type is an interface as it is not possible,
|
|
before execution time, to know for certain if the type can be serialized or not.
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
class NonSerializableClass {
|
|
}
|
|
[Serializable]
|
|
class SerializableClass {
|
|
NonSerializableClass field;
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example:
|
|
<code>
|
|
class NonSerializableClass {
|
|
}
|
|
[Serializable]
|
|
class SerializableClass {
|
|
[NonSerialized]
|
|
NonSerializableClass field;
|
|
}
|
|
</code></example>
|
|
<remarks>This rule is available since Gendarme 2.0</remarks>
|
|
</member>
|
|
<member name="T:Gendarme.Rules.Serialization.MarkEnumerationsAsSerializableRule">
|
|
<summary>
|
|
This rule warns when it founds an <c>enum</c> that is not decorated with
|
|
a <c>[Serializable]</c> attribute. Enums, even without the attribute,
|
|
are always serializable. Marking them as such makes the source code more readable.
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
public enum Colors {
|
|
Black,
|
|
White
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example:
|
|
<code>
|
|
[Serializable]
|
|
public enum Colors {
|
|
Black,
|
|
White
|
|
}
|
|
</code></example>
|
|
<remarks>This rule is available since Gendarme 2.2</remarks>
|
|
</member>
|
|
<member name="T:Gendarme.Rules.Serialization.MissingSerializableAttributeOnISerializableTypeRule">
|
|
<summary>
|
|
This rule checks for types that implement <c>System.ISerializable</c> but are
|
|
not decorated with the <c>[Serializable]</c> attribute. Implementing
|
|
<c>System.ISerializable</c> is not enough to make a class serializable as this
|
|
interface only gives you more control over the basic serialization process.
|
|
In order for the runtime to know your type is serializable it must have the
|
|
<c>[Serializable]</c> attribute.
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
// this type cannot be serialized by the runtime
|
|
public class Bad : ISerializable {
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example:
|
|
<code>
|
|
[Serializable]
|
|
public class Good : ISerializable {
|
|
}
|
|
</code></example>
|
|
<remarks>This rule is available since Gendarme 2.0</remarks>
|
|
</member>
|
|
<member name="T:Gendarme.Rules.Serialization.MissingSerializationConstructorRule">
|
|
<summary>
|
|
This rule checks for types that implement <c>System.ISerializable</c> but don't provide a
|
|
serialization constructor. The constructor is required in order to make the type
|
|
serializeable but cannot be enforced by the interface.
|
|
The serialization constructor should be <c>private</c> for <c>sealed</c> types and
|
|
<c>protected</c> for unsealed types.
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
[Serializable]
|
|
public class Bad : ISerializable {
|
|
public void GetObjectData (SerializationInfo info, StreamingContext context)
|
|
{
|
|
}
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example (sealed):
|
|
<code>
|
|
[Serializable]
|
|
public sealed class Good : ISerializable {
|
|
private ClassWithConstructor (SerializationInfo info, StreamingContext context)
|
|
{
|
|
}
|
|
public void GetObjectData (SerializationInfo info, StreamingContext context)
|
|
{
|
|
}
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example:
|
|
<code>
|
|
[Serializable]
|
|
public class Good : ISerializable {
|
|
protected ClassWithConstructor (SerializationInfo info, StreamingContext context)
|
|
{
|
|
}
|
|
public void GetObjectData (SerializationInfo info, StreamingContext context)
|
|
{
|
|
}
|
|
}
|
|
</code></example>
|
|
<remarks>This rule is available since Gendarme 2.0</remarks>
|
|
</member>
|
|
<member name="T:Gendarme.Rules.Serialization.UseCorrectSignatureForSerializationMethodsRule">
|
|
<summary>
|
|
This rule checks for methods which use the serialization attributes:
|
|
<c>[OnSerializing, OnDeserializing, OnSerialized, OnDeserialized]</c>. You must
|
|
ensure that these methods have the correct signature. They should be <c>private</c>,
|
|
return <c>void</c> and have a single parameter of type <c>StreamingContext</c>.
|
|
Failure to have the right signature can, in some circumstances, make your assembly
|
|
unusable at runtime.
|
|
</summary>
|
|
<example>
|
|
Bad example:
|
|
<code>
|
|
[Serializable]
|
|
public class Bad {
|
|
[OnSerializing]
|
|
public bool Serializing (StreamingContext context)
|
|
{
|
|
}
|
|
}
|
|
</code></example>
|
|
<example>
|
|
Good example:
|
|
<code>
|
|
[Serializable]
|
|
public class BadClass {
|
|
[OnSerializing]
|
|
private void Serializing (StreamingContext context)
|
|
{
|
|
}
|
|
}
|
|
</code></example>
|
|
<remarks>This rule is available since Gendarme 2.0</remarks>
|
|
</member>
|
|
</members>
|
|
</doc>
|