Udostępnij przez

Zmiany przełomowe

Ważne jest, aby biblioteka platformy .NET znalazła równowagę między stabilnością istniejących użytkowników a innowacjami w przyszłości. Autorzy bibliotek mają tendencję do refaktoryzowania i przemyślenia kodu do momentu, gdy będzie idealny, ale naruszanie zgodności z istniejącymi użytkownikami może mieć negatywne skutki, szczególnie w przypadku bibliotek o niskim poziomie.

Typy projektów i zmiany powodujące niezgodność

Sposób, w jaki społeczność .NET używa biblioteki, wpływa na skutki zmian powodujących niezgodność dla deweloperów tworzących aplikacje dla użytkowników końcowych.

  • Biblioteki niskiego i środkowego poziomu , takie jak serializator, analizator HTML, maper obiektów bazy danych lub struktura internetowa, są najbardziej dotknięte zmianami powodujących niezgodność.

    Pakiety bloków konstrukcyjnych są używane przez deweloperów końcowych do tworzenia aplikacji oraz przez inne biblioteki jako zależności NuGet. Na przykład tworzysz aplikację i używasz klienta open source do wywoływania usługi internetowej. Aktualizacja zakłócająca działanie biblioteki używanej przez klienta nie jest czymś, co można naprawić. Jest to klient typu open source, który musi zostać zmieniony i nie masz nad nim żadnej kontroli. Musisz znaleźć zgodne wersje bibliotek lub przesłać poprawkę do biblioteki klienta i poczekać na nową wersję. Najgorszą sytuacją jest użycie dwóch bibliotek, które zależą od wzajemnie niezgodnych wersji trzeciej biblioteki.

  • Biblioteki wysokiego poziomu, takie jak zestaw kontrolek interfejsu użytkownika, są mniej wrażliwe na zmiany powodujące problemy z kompatybilnością.

    Biblioteki wysokiego poziomu są bezpośrednio przywołyne w aplikacji użytkownika końcowego. W przypadku wystąpienia zmian powodujących niezgodność deweloper może zdecydować się na aktualizację do najnowszej wersji lub zmodyfikować aplikację, aby mogła pracować ze zmianą powodującą niezgodność.

✔️ Zastanów się, jak będzie używana biblioteka. Jaki wpływ będą miały wprowadzane zmiany na aplikacje i biblioteki, które z nich korzystają?

✔️ Zminimalizuj zmiany powodujące niezgodność podczas tworzenia biblioteki platformy .NET niskiego poziomu.

✔️ ROZWAŻ opublikowanie znacznego przerobienia biblioteki jako nowego pakietu NuGet.

Typy zmian łamiących zgodność

Zmiany powodujące niezgodność dzielą się na różne kategorie i nie mają równego wpływu.

Zmiana powodująca niezgodność źródła

Zmiana w kodzie źródłowym powodująca niezgodność nie wpływa na działanie programu, ale spowoduje błędy kompilacji podczas następnej kompilacji aplikacji. Na przykład nowe przeciążenie może utworzyć niejednoznaczność wywołań metod, które były jednoznaczne wcześniej, lub zmieniona nazwa parametru spowoduje przerwanie wywołań używających nazwanych parametrów.

public class Task
{
    // Adding a type called Task could conflict with System.Threading.Tasks.Task at compilation
}

Ponieważ zmiana powodująca niezgodność źródła jest szkodliwa tylko wtedy, gdy deweloperzy ponownie skompilują swoje aplikacje, jest to najmniej destrukcyjna zmiana powodująca niezgodność. Deweloperzy mogą łatwo naprawić własny uszkodzony kod źródłowy.

Zmiana powodująca zmianę zachowania

Zmiany zachowania są najczęstszym typem zmiany powodującej niezgodność: prawie każda zmiana zachowania może spowodować błąd logiki dla użytkownika. Zmiany w bibliotece, takie jak sygnatury metod, zgłaszane wyjątki lub formaty danych wejściowych czy wyjściowych, mogą negatywnie wpłynąć na użytkowników biblioteki. Nawet poprawka błędów może kwalifikować się jako zmiana zakłócająca, jeśli użytkownicy polegali na wcześniej błędnym działaniu.

Dodawanie funkcji i poprawianie złych zachowań jest dobrą rzeczą, ale bez opieki może to utrudnić istniejącym użytkownikom uaktualnienie. Jednym z podejść ułatwiających deweloperom radzenie sobie ze zmianami łamiącymi zachowanie jest ukrycie ich poprzez ustawienia. Ustawienia umożliwiają deweloperom aktualizowanie do najnowszej wersji biblioteki, jednocześnie dając możliwość wyrażenia zgody na zmiany powodujące niekompatybilność lub zrezygnowania z takich zmian. Ta strategia pozwala deweloperom pozostawać na bieżąco, jednocześnie umożliwiając ich kodowi dostosowywanie się z upływem czasu.

Na przykład ASP.NET Core MVC ma koncepcję wersji zgodności , która modyfikuje funkcje włączone i wyłączone w systemie MvcOptions.

✔️ ROZWAŻ pozostawienie nowych funkcji domyślnie wyłączonych, jeśli mają wpływ na istniejących użytkowników, a deweloperzy mogą zdecydować się na tę funkcję za pomocą ustawienia.

Aby uzyskać więcej informacji na temat zmian w zachowaniu powodujących problemy w interfejsach API platformy .NET, zobacz Zgodność zmian behawioralnych platformy .NET.

Zmiana powodująca niezgodność binarną

Zmiana przełamująca zgodność binarną występuje, gdy zmienisz publiczny interfejs API swojej biblioteki, tak że zestawy skompilowane do starszych wersji tej biblioteki nie są już w stanie wywołać API. Na przykład zmiana sygnatury metody przez dodanie nowego parametru spowoduje, że zestawy skompilowane względem starszej wersji biblioteki będą rzucać wyjątek MissingMethodException.

Zmiana powodująca niezgodność binarną może również spowodować awarię całego zestawu. Zmiana nazwy zestawu za pomocą AssemblyName spowoduje zmianę jego tożsamości, podobnie jak dodanie, usunięcie lub zmiana jego klucza silnego nazewnictwa. Zmiana tożsamości zestawu spowoduje unieważnienie wszystkiego skompilowanego kodu, który z niego korzysta.

❌ NIE ZMIENIAJ NAZWY ZESTAWU.

❌ NIE dodawaj, usuwaj ani zmieniaj silnego klucza nazewnictwa.

✔️ ROZWAŻ użycie abstrakcyjnych klas bazowych zamiast interfejsów.

Dodanie dowolnego elementu do interfejsu spowoduje, że istniejące typy implementujące go kończą się niepowodzeniem. Abstrakcyjna klasa bazowa umożliwia dodanie domyślnej implementacji wirtualnej.

✔️ ROZWAŻ umieszczenie ObsoleteAttribute na typach i elementach członkowskich, które zamierzasz usunąć. Atrybut powinien mieć instrukcje dotyczące aktualizowania kodu, aby nie używać przestarzałego interfejsu API.

Kod, który wywołuje typy i metody oznaczone za pomocą ObsoleteAttribute, spowoduje wygenerowanie ostrzeżenia kompilacji z wiadomością przypisaną do atrybutu. Ostrzeżenia dają osobom, które używają przestarzałej powierzchni interfejsu API, czas na migrację, tak aby po usunięciu przestarzałego interfejsu API większość osób już z niego nie korzystała.

public class Document
{
    [Obsolete("LoadDocument(string) is obsolete. Use LoadDocument(Uri) instead.")]
    public static Document LoadDocument(string uri)
    {
        return LoadDocument(new Uri(uri));
    }

    public static Document LoadDocument(Uri uri)
    {
        // Load the document
    }
}

✔️ Rozważ przechowywanie typów i metod ObsoleteAttribute bezterminowo w bibliotekach o niskim i średnim poziomie.

Usuwanie interfejsów API jest zmianą powodującą niezgodność binarną. Rozważ utrzymanie przestarzałych typów i metod, jeśli koszt ich utrzymania jest niski i nie dodaje znacznego długu technicznego do twojej biblioteki. Brak usuwania typów i metod może pomóc uniknąć najgorszych scenariuszy wymienionych powyżej.

Aby uzyskać więcej informacji na temat zmian interfejsu API platformy .NET, które przerywają zgodność binarną, zobacz Zgodność kontraktu publicznego platformy .NET.

Zobacz także

Poprzednie

  • Last updated on