Overwegingen voor versies en updates voor C#-ontwikkelaars

Compatibiliteit is een belangrijk doel omdat nieuwe functies worden toegevoegd aan de C#-taal. In bijna alle gevallen kan bestaande code zonder problemen opnieuw worden gecompileerd met een nieuwe compilerversie. Het .NET Runtime-team heeft ook een doel om compatibiliteit voor bijgewerkte bibliotheken te garanderen. In bijna alle gevallen, wanneer uw app wordt gestart vanuit een bijgewerkte runtime met bijgewerkte bibliotheken, is het gedrag precies hetzelfde als bij eerdere versies.

De taalversie die wordt gebruikt om uw app te compileren, komt doorgaans overeen met de runtime target framework moniker (TFM) waarnaar wordt verwezen in uw project. Zie het artikel getiteld Uw taalversie configureren voor meer informatie over het wijzigen van de standaardtaalversie. Dit standaardgedrag zorgt voor maximale compatibiliteit.

Wanneer belangrijke wijzigingen worden geïntroduceerd, worden ze geclassificeerd als:

• Wijziging die fouten veroorzaakt door binaire fouten: een binaire wijziging veroorzaakt een ander gedrag, waaronder mogelijk vastlopen, in uw toepassing of bibliotheek wanneer deze wordt gestart met behulp van een nieuwe runtime. U moet uw app opnieuw compileren om deze wijzigingen op te nemen. Het bestaande binaire bestand werkt niet correct.
• Wijziging die fouten veroorzaken bij bron: een wijziging die fouten in de bron aanbrengt, verandert de betekenis van uw broncode. U moet broncodebewerkingen maken voordat u uw toepassing compileert met de nieuwste taalversie. Uw bestaande binaire bestand wordt correct uitgevoerd met de nieuwere host en runtime. Houd er rekening mee dat voor taalsyntaxis een wijziging die fouten optreedt in de bron ook een gedragswijziging is, zoals gedefinieerd in de wijzigingen die fouten veroorzaken in runtime.

Wanneer een binaire wijziging van invloed is op uw app, moet u uw app opnieuw compileren, maar u hoeft geen broncode te bewerken. Wanneer een wijziging die fouten in de bron aanbrengt, van invloed is op uw app, wordt het bestaande binaire bestand nog steeds correct uitgevoerd in omgevingen met de bijgewerkte runtime en bibliotheken. U moet echter bronwijzigingen aanbrengen om opnieuw te compileren met de nieuwe taalversie en runtime. Als een wijziging zowel bronbreking als binaire fouten is, moet u uw toepassing opnieuw compileren met de nieuwste versie en bronupdates uitvoeren.

Vanwege het doel om te voorkomen dat wijzigingen worden veroorzaakt door het C#-taalteam en het runtimeteam, is het bijwerken van uw toepassing meestal een kwestie van het bijwerken van de TFM en het opnieuw bouwen van de app. Voor bibliotheken die openbaar worden gedistribueerd, moet u uw beleid echter zorgvuldig evalueren voor ondersteunde TFM's en ondersteunde taalversies. Mogelijk maakt u een nieuwe bibliotheek met functies in de nieuwste versie en moet u ervoor zorgen dat apps die zijn gebouwd met eerdere versies van de compiler, deze kunnen gebruiken. Of u kunt een bestaande bibliotheek upgraden en veel van uw gebruikers hebben mogelijk nog geen bijgewerkte versies.

Inleiding tot belangrijke wijzigingen in uw bibliotheken

Wanneer u nieuwe taalfuncties in de openbare API van uw bibliotheek gebruikt, moet u evalueren of de functie een binaire of bronwijziging introduceert voor de gebruikers van uw bibliotheek. Wijzigingen in uw interne implementatie die niet in de public of protected interfaces worden weergegeven, zijn compatibel.

Notitie

Als u typen System.Runtime.CompilerServices.InternalsVisibleToAttribute inschakelt om interne leden te zien, kunnen de interne leden wijzigingen veroorzaken die fouten veroorzaken.

Voor een wijziging met binaire fouten moeten uw gebruikers hun code opnieuw compileren om de nieuwe versie te kunnen gebruiken. Denk bijvoorbeeld aan deze openbare methode:

public double CalculateSquare(double value) => value * value;

Als u de in wijzigingsfunctie aan de methode toevoegt, is dat een wijziging die fouten met binaire fouten aanbrengt:

public double CalculateSquare(in double value) => value * value;

Gebruikers moeten elke toepassing die gebruikmaakt van de CalculateSquare methode voor de nieuwe bibliotheek opnieuw compileren om correct te kunnen werken.

Voor een wijziging die fouten in de bron optreedt, moeten uw gebruikers hun code wijzigen voordat ze opnieuw worden gecompileren. Denk bijvoorbeeld aan dit type:

public class Person
{
    public string FirstName { get; }
    public string LastName { get; }

    public Person(string firstName, string lastName) => (FirstName, LastName) = (firstName, lastName);

    // other details omitted
}

In een nieuwere versie wilt u profiteren van de gesynthetiseerde leden die zijn gegenereerd voor record typen. U wijzigt de volgende wijziging:

public record class Person(string FirstName, string LastName);

Voor de vorige wijziging zijn wijzigingen vereist voor elk type dat is afgeleid van Person. Al deze declaraties moeten de record wijzigingsfunctie toevoegen aan hun declaraties.

Gevolgen van wijzigingen die fouten veroorzaken

Wanneer u een binaire wijziging aan uw bibliotheek toevoegt, dwingt u alle projecten die uw bibliotheek gebruiken opnieuw te compileren. Geen van de broncode in deze projecten moet echter worden gewijzigd. Als gevolg hiervan is de impact van de wijziging die fouten veroorzaken redelijk klein voor elk project.

Wanneer u een bronwijziging aanbrengt die fouten in uw bibliotheek aanbrengt, moeten alle projecten bronwijzigingen aanbrengen om de nieuwe bibliotheek te kunnen gebruiken. Als voor de benodigde wijziging nieuwe taalfuncties zijn vereist, dwingt u deze projecten om een upgrade uit te voeren naar dezelfde taalversie en TFM die u nu gebruikt. U hebt meer werk nodig voor uw gebruikers en hebt ze mogelijk ook gedwongen een upgrade uit te voeren.

De impact van wijzigingen die fouten veroorzaken die u aanbrengt, is afhankelijk van het aantal projecten dat afhankelijk is van uw bibliotheek. Als uw bibliotheek intern wordt gebruikt door een paar toepassingen, kunt u reageren op belangrijke wijzigingen in alle betrokken projecten. Als uw bibliotheek echter openbaar wordt gedownload, moet u de mogelijke impact evalueren en alternatieven overwegen:

• U kunt nieuwe API's toevoegen die parallel bestaande API's zijn.
• U kunt parallelle builds overwegen voor verschillende TFM's.
• U kunt overwegen om meerdere doelgroepen te gebruiken.