Wijzigingen die fouten veroorzaken
Het is belangrijk voor een .NET-bibliotheek om een evenwicht te vinden tussen stabiliteit voor bestaande gebruikers en innovatie voor de toekomst. Bibliotheekauteurs leunen op het herstructureren en herzien van code totdat ze perfect zijn, maar het breken van uw bestaande gebruikers heeft een negatieve invloed, met name voor bibliotheken op laag niveau.
Projecttypen en belangrijke wijzigingen
Hoe een bibliotheek wordt gebruikt door de .NET-community wijzigt het effect van belangrijke wijzigingen voor eindgebruikersontwikkelaars.
Bibliotheken op laag en middelste niveau , zoals een serializer, HTML-parser, relationele mapper van databaseobjecten of webframework, worden het meest beïnvloed door wijzigingen die fouten veroorzaken.
Bouwsteenpakketten worden gebruikt door eindgebruikers om toepassingen te bouwen en door andere bibliotheken als NuGet-afhankelijkheden. U bouwt bijvoorbeeld een toepassing en gebruikt een opensource-client om een webservice aan te roepen. Een belangrijke update voor een afhankelijkheid die door de client wordt gebruikt, is niet iets wat u kunt oplossen. Het is de opensource-client die moet worden gewijzigd en u hebt geen controle over deze client. U moet compatibele versies van de bibliotheken vinden of een oplossing indienen bij de clientbibliotheek en wachten op een nieuwe versie. De ergste situatie is als u twee bibliotheken wilt gebruiken die afhankelijk zijn van wederzijds incompatibele versies van een derde bibliotheek.
Bibliotheken op hoog niveau , zoals een reeks besturingselementen voor de gebruikersinterface, zijn minder gevoelig voor belangrijke wijzigingen.
Er wordt rechtstreeks naar bibliotheken op hoog niveau verwezen in een toepassing voor eindgebruikers. Als er wijzigingen optreden die fouten veroorzaken, kan de ontwikkelaar ervoor kiezen om bij te werken naar de nieuwste versie of kan de toepassing wijzigen om te werken met de wijziging die fouten veroorzaken.
✔️ Denk na over hoe uw bibliotheek wordt gebruikt. Welk effect hebben wijzigingen die fouten veroorzaken in toepassingen en bibliotheken die deze gebruiken?
✔️ Minimaliseer belangrijke wijzigingen bij het ontwikkelen van een .NET-bibliotheek op laag niveau.
✔️ OVERWEEG een groot herschrijven van een bibliotheek te publiceren als een nieuw NuGet-pakket.
Typen belangrijke wijzigingen
Wijzigingen die fouten veroorzaken, vallen in verschillende categorieën en zijn niet even impactvol.
Wijziging die fouten in bron aanbreekt
Een wijziging die fouten veroorzaakt die fouten veroorzaakt in het programma, heeft geen invloed op de uitvoering van het programma, maar veroorzaakt compilatiefouten de volgende keer dat de toepassing opnieuw wordt gecompileerd. Een nieuwe overbelasting kan bijvoorbeeld een dubbelzinnigheid creëren in methodeaanroepen die eerder ondubbelzinnig waren, of een hernoemde parameter onderbreekt bellers die benoemde parameters gebruiken.
public class Task
{
// Adding a type called Task could conflict with System.Threading.Tasks.Task at compilation
}
Omdat een wijziging die fouten veroorzaakt door de bron alleen schadelijk is wanneer ontwikkelaars hun toepassingen opnieuw compileren, is dit de minst verstorende wijziging. Ontwikkelaars kunnen hun eigen verbroken broncode eenvoudig herstellen.
Wijziging die fouten veroorzaken in gedrag
Gedragswijzigingen zijn het meest voorkomende type belangrijke wijziging: vrijwel elke wijziging in gedrag kan een logische fout voor een consument veroorzaken. Wijzigingen in uw bibliotheek, zoals methodehandtekeningen, uitzonderingen die zijn gegenereerd of invoer- of uitvoergegevensindelingen, kunnen allemaal negatieve gevolgen hebben voor uw bibliotheekgebruikers. Zelfs een foutoplossing kan in aanmerking komen als een belangrijke wijziging als gebruikers afhankelijk waren van het eerder verbroken gedrag.
Het toevoegen van functies en het verbeteren van slecht gedrag is een goede zaak, maar zonder dat dit belangrijk is, kan het voor bestaande gebruikers heel moeilijk zijn om een upgrade uit te voeren. Een manier om ontwikkelaars te helpen omgaan met wijzigingen die fouten veroorzaken, is door ze achter instellingen te verbergen. Instellingen ontwikkelaars laten bijwerken naar de nieuwste versie van uw bibliotheek en tegelijkertijd ervoor kiezen om ervoor te kiezen om wijzigingen die fouten veroorzaken, in of uit te schakelen. Met deze strategie kunnen ontwikkelaars up-to-date blijven terwijl ze hun verbruikende code in de loop van de tijd kunnen aanpassen.
ASP.NET Core MVC heeft bijvoorbeeld het concept van een compatibiliteitsversie waarmee de ingeschakelde en uitgeschakelde MvcOptionsfuncties worden gewijzigd.
✔️ OVERWEEG om nieuwe functies standaard uit te schakelen, als ze van invloed zijn op bestaande gebruikers en ontwikkelaars toestaan zich met een instelling voor de functie aan te sluiten.
Zie de compatibiliteit met .NET-gedragswijzigingen voor meer informatie over gedrag dat fouten in .NET API's aanbreekt.
Wijziging voor binaire fouten
Er treedt een binaire wijziging op wanneer u de openbare API van uw bibliotheek wijzigt, zodat assembly's die zijn gecompileerd op oudere versies van uw bibliotheek, de API niet meer kunnen aanroepen. Als u bijvoorbeeld de handtekening van een methode wijzigt door een nieuwe parameter toe te voegen, worden assembly's gecompileerd op basis van de oudere versie van de bibliotheek.MissingMethodException
Een binaire wijziging die fouten aanbrengt, kan ook een hele assembly verbreken. Als u de naam van een assembly AssemblyName wijzigt, verandert de identiteit van de assembly, zoals het toevoegen, verwijderen of wijzigen van de sterke naamgevingssleutel van de assembly. Een wijziging van de identiteit van een assembly breekt alle gecompileerde code die deze gebruikt.
❌ Wijzig geen assemblynaam.
❌ VOEG NIET de sterke naamgevingssleutel toe, verwijder of wijzig deze.
✔️ OVERWEEG abstracte basisklassen te gebruiken in plaats van interfaces.
Als u iets toevoegt aan een interface, mislukken bestaande typen die deze implementeren. Met een abstracte basisklasse kunt u een standaard virtuele implementatie toevoegen.
✔️ OVERWEEG de ObsoleteAttribute typen en leden die u wilt verwijderen te plaatsen. Het kenmerk moet instructies hebben voor het bijwerken van code om de verouderde API niet meer te gebruiken.
Code waarmee typen en methoden worden aangeroepen, ObsoleteAttribute genereert een buildwaarschuwing met het bericht dat is opgegeven aan het kenmerk. De waarschuwingen geven mensen die de verouderde API-oppervlaktetijd gebruiken om te migreren, zodat de meeste gebruikers deze niet meer gebruiken wanneer de verouderde API wordt verwijderd.
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
}
}
✔️ OVERWEEG typen en methoden voor ObsoleteAttribute onbepaalde tijd in bibliotheken op laag en middelste niveau te bewaren.
Het verwijderen van API's is een binaire wijziging die fouten optreedt. Overweeg verouderde typen en methoden te behouden als ze goedkoop worden onderhouden en er geen technische schulden aan uw bibliotheek worden toegevoegd. Het verwijderen van typen en methoden kan helpen bij het voorkomen van de ergste scenario's die hierboven worden genoemd.
Zie de compatibiliteit van openbare .NET-contracten voor meer informatie over welke .NET API-wijzigingen de binaire compatibiliteit verbreken.
