将显式接口实现转换为隐式接口实现。

打破:来源

受影响语言:所有

将显式接口实现重构为隐式接口实现在如何破坏API方面更为微妙。从表面上看，这似乎是相对安全的，然而，当与继承结合在一起时，它可能会导致问题。

更改前的API:

public class Foo : IEnumerable
{
    IEnumerator IEnumerable.GetEnumerator() { yield return "Foo"; }
}

API变更后:

public class Foo : IEnumerable
{
    public IEnumerator GetEnumerator() { yield return "Foo"; }
}

样例客户端代码在更改前工作，更改后被破坏:

class Bar : Foo, IEnumerable
{
    IEnumerator IEnumerable.GetEnumerator() // silently hides base instance
    { yield return "Bar"; }
}

foreach( var x in new Bar() )
    Console.WriteLine(x);    // originally output "Bar", now outputs "Foo"

重命名接口

休息一下:源代码和二进制文件

受影响的语言:很可能全部，用c#测试。

更改前的API:

public interface IFoo
{
    void Test();
}

public class Bar
{
    IFoo GetFoo() { return new Foo(); }
}

API变更后:

public interface IFooNew // Of the exact same definition as the (old) IFoo
{
    void Test();
}

public class Bar
{
    IFooNew GetFoo() { return new Foo(); }
}

示例客户端代码，可以工作，但随后被破坏:

new Bar().GetFoo().Test(); // Binary only break
IFoo foo = new Bar().GetFoo(); // Source and binary break

Visual Studio扩展NDepend在API Breaking Changes类别中提供了几个规则来检测二进制级别的中断。只有定义了NDepend基线，这些规则才会执行。

API Breaking Changes: Types: This rule warns if a type publicly visible in the baseline, is not publicly visible anymore or if it has been removed. Clients code using such type will be broken. API Breaking Changes: Methods: This rule warns if a method publicly visible in the baseline, is not publicly visible anymore or if it has been removed. Clients code using such method will be broken. Note that if a method signature gets changed the old method version is seen as removed and the new method version is seen as added, so a breaking change will be detected on the old method version. API Breaking Changes: Fields: This rule warns if a field publicly visible in the baseline, is not publicly visible anymore or if it has been removed. Clients code using such field will be broken. API Breaking Changes: Interfaces and Abstract Classes: This rule warns if a publicly visible interface or abstract class has been changed and contains new abstract methods or if some abstract methods have been removed. Clients code that implement such interface or derive from such abstract class will be broken. Broken serializable types: This rule warns about breaking changes in types tagged with SerializableAttribute. To do so, this rule searches for serializable type with serializable instance fields added or removed since the baseline. Notice that it doesn't take account of fields tagged with NonSerializedAttribute. Avoid changing enumerations Flags status: This rule matches enumeration types that used to be tagged with FlagsAttribute in the baseline, and not anymore. It also matches the opposite, enumeration types that are now tagged with FlagsAttribute, and were not tagged in the baseline. Being tagged with FlagsAttribute is a strong property for an enumeration. Not so much in terms of behavior (only the enum.ToString() method behavior changes when an enumeration is tagged with FlagsAttribute) but in terms of meaning: is the enumeration a range of values or a range of flags?

还有3个代码查询建议让用户浏览新的公共API元素:

新的公开可见类型。 新的公开可见方法。 新的公开可见字段。

将显式接口实现转换为隐式接口实现。

打破:来源

受影响语言:所有

将显式接口实现重构为隐式接口实现在如何破坏API方面更为微妙。从表面上看，这似乎是相对安全的，然而，当与继承结合在一起时，它可能会导致问题。

更改前的API:

public class Foo : IEnumerable
{
    IEnumerator IEnumerable.GetEnumerator() { yield return "Foo"; }
}

API变更后:

public class Foo : IEnumerable
{
    public IEnumerator GetEnumerator() { yield return "Foo"; }
}

样例客户端代码在更改前工作，更改后被破坏:

class Bar : Foo, IEnumerable
{
    IEnumerator IEnumerable.GetEnumerator() // silently hides base instance
    { yield return "Bar"; }
}

foreach( var x in new Bar() )
    Console.WriteLine(x);    // originally output "Bar", now outputs "Foo"

名称空间之外

源级中断/源级安静语义更改

由于vb中命名空间解析的工作方式。Net中，向库中添加名称空间会导致使用以前版本的API编译的Visual Basic代码不能使用新版本编译。

示例客户端代码:

Imports System
Imports Api.SomeNamespace

Public Class Foo
    Public Sub Bar()
        Dim dr As Data.DataRow
    End Sub
End Class

如果API的新版本添加了API . somenamespace。数据，则上述代码将无法编译。

使用项目级名称空间导入会变得更加复杂。如果上面的代码中省略了Imports System，但是在项目级别导入了System名称空间，那么代码仍然可能导致错误。

然而，如果Api在它的Api. somenamspace . data命名空间中包含一个类DataRow，那么代码将被编译，但dr将是System.Data.DataRow的一个实例，当使用旧版本的Api编译时，当使用新版本的Api编译时，则是Api. somenamspace . data .DataRow。

参数重命名

源代码级打破

改变参数的名称是vb.net从版本7(?)(。Net版本1?)和c#. Net版本4(。Net版本4)。

更改前的API:

namespace SomeNamespace {
    public class Foo {
        public static void Bar(string x) {
           ...
        }
    }
}

更改后的API:

namespace SomeNamespace {
    public class Foo {
        public static void Bar(string y) {
           ...
        }
    }
}

示例客户端代码:

Api.SomeNamespace.Foo.Bar(x:"hi"); //C#
Api.SomeNamespace.Foo.Bar(x:="hi") 'VB

参考参数

源代码级打破

添加具有相同签名的方法重写，只是其中一个参数是通过引用而不是通过值传递的，这将导致引用API的vb源代码无法解析该函数。Visual Basic没有办法(?)在调用点区分这些方法，除非它们有不同的参数名，所以这样的更改可能导致两个成员在vb代码中都不可用。

更改前的API:

namespace SomeNamespace {
    public class Foo {
        public static void Bar(string x) {
           ...
        }
    }
}

更改后的API:

namespace SomeNamespace {
    public class Foo {
        public static void Bar(string x) {
           ...
        }
        public static void Bar(ref string x) {
           ...
        }
    }
}

示例客户端代码:

Api.SomeNamespace.Foo.Bar(str)

从字段到属性更改

二进制级中断/源代码级中断

除了明显的二进制级中断外，如果通过引用将成员传递给方法，还可能导致源级中断。

更改前的API:

namespace SomeNamespace {
    public class Foo {
        public int Bar;
    }
}

更改后的API:

namespace SomeNamespace {
    public class Foo {
        public int Bar { get; set; }
    }
}

示例客户端代码:

FooBar(ref Api.SomeNamespace.Foo.Bar);

添加重载方法以终止默认参数的使用

中断类型:源级安静语义更改

由于编译器将缺少默认参数值的方法调用转换为调用端具有默认值的显式调用，因此提供了与现有编译代码的兼容性;将为之前编译的所有代码找到具有正确签名的方法。

另一方面，不使用可选参数的调用现在被编译为对缺少可选参数的新方法的调用。这一切仍然正常工作，但是如果被调用的代码位于另一个程序集中，那么调用它的新编译代码现在依赖于该程序集中的新版本。部署调用重构代码的程序集而不部署重构代码所在的程序集将导致“方法未找到”异常。

更改前的API

  public int MyMethod(int mandatoryParameter, int optionalParameter = 0)
  {
     return mandatoryParameter + optionalParameter;
  }    

更改后的API

  public int MyMethod(int mandatoryParameter, int optionalParameter)
  {
     return mandatoryParameter + optionalParameter;
  }

  public int MyMethod(int mandatoryParameter)
  {
     return MyMethod(mandatoryParameter, 0);
  }

仍然可以工作的示例代码

  public int CodeNotDependentToNewVersion()
  {
     return MyMethod(5, 6); 
  }

在编译时依赖于新版本的示例代码

  public int CodeDependentToNewVersion()
  {
     return MyMethod(5); 
  }