重新排序枚举值

中断类型:源级/二进制级安静语义更改

受影响语言:全部

重新排序枚举值将保持源级兼容性，因为字面量具有相同的名称，但它们的序号索引将被更新，这可能导致某些类型的静默源级中断。

更糟糕的是，如果客户端代码没有根据新的API版本重新编译，就会引入无声的二进制级中断。Enum值是编译时的常量，因此任何对它们的使用都会被写入客户端程序集的IL中。这种情况有时尤其难以发现。

更改前的API

public enum Foo
{
   Bar,
   Baz
}

更改后的API

public enum Foo
{
   Baz,
   Bar
}

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

Foo.Bar < Foo.Baz

重新排序枚举值

中断类型:源级/二进制级安静语义更改

受影响语言:全部

重新排序枚举值将保持源级兼容性，因为字面量具有相同的名称，但它们的序号索引将被更新，这可能导致某些类型的静默源级中断。

更糟糕的是，如果客户端代码没有根据新的API版本重新编译，就会引入无声的二进制级中断。Enum值是编译时的常量，因此任何对它们的使用都会被写入客户端程序集的IL中。这种情况有时尤其难以发现。

更改前的API

public enum Foo
{
   Bar,
   Baz
}

更改后的API

public enum Foo
{
   Baz,
   Bar
}

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

Foo.Bar < Foo.Baz

名称空间之外

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

由于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);

更改方法签名

类型:二进制级别的中断

受影响的语言:c#(最有可能是VB和f#，但未经测试)

更改前的API

public static class Foo
{
    public static void bar(int i);
}

更改后的API

public static class Foo
{
    public static bool bar(int i);
}

在更改前工作的示例客户端代码

Foo.bar(13);

当我发现它时，这一点非常不明显，特别是考虑到接口的相同情况。这根本不是一个休息，但我决定把它包括在内，这是足够令人惊讶的:

将类成员重构为基类

Kind:不休息!

受影响的语言:无(即没有损坏)

更改前的API:

class Foo
{
    public virtual void Bar() {}
    public virtual void Baz() {}
}

更改后的API:

class FooBase
{
    public virtual void Bar() {}
}

class Foo : FooBase
{
    public virtual void Baz() {}
}

在整个更改过程中保持工作的示例代码(即使我预计它会中断):

// C++/CLI
ref class Derived : Foo
{
   public virtual void Baz() {{

   // Explicit override    
   public virtual void BarOverride() = Foo::Bar {}
};

注:

C++/CLI is the only .NET language that has a construct analogous to explicit interface implementation for virtual base class members - "explicit override". I fully expected that to result in the same kind of breakage as when moving interface members to a base interface (since IL generated for explicit override is the same as for explicit implementation). To my surprise, this is not the case - even though generated IL still specifies that BarOverride overrides Foo::Bar rather than FooBase::Bar, assembly loader is smart enough to substitute one for another correctly without any complaints - apparently, the fact that Foo is a class is what makes the difference. Go figure...

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

打破:来源

受影响语言:所有

将显式接口实现重构为隐式接口实现在如何破坏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"