Boş değer atanabilir başvuru türleri (C# başvurusu)

Not

Bu makale null atanabilir başvuru türlerini kapsar. Null atanabilir değer türlerini de bildirebilirsiniz.

Null değer atanabilir algılama bağlamındaki kodda null atanabilir başvuru türlerini kullanın. Null atanabilir başvuru türleri, null statik analiz uyarıları ve null-forgiving işleci isteğe bağlı dil özellikleridir. Tümü varsayılan olarak kapalıdır. Derleme ayarlarını kullanarak proje düzeyinde veya pragmalar kullanarak kodda null atanabilir bağlamı denetleyebilirsiniz.

C# dili başvuru belgesi, C# dilinin en son yayımlanan sürümünü gösterir. Ayrıca, yaklaşan dil sürümü için genel önizlemelerdeki özelliklere yönelik ilk belgeleri içerir.

Belgelerde ilk olarak dilin son üç sürümünde veya geçerli genel önizlemelerde sunulan tüm özellikler tanımlanır.

Tavsiye

Bir özelliğin C# dilinde ilk tanıtıldığı zamanları bulmak için C# dil sürümü geçmişi makalesine bakın.

Önemli

Tüm proje şablonları, proje için null atanabilir bağlam etkinleştirir. Önceki şablonlarla oluşturulan projeler bu öğeyi içermez ve bunları proje dosyasında etkinleştirmediğiniz veya pragmaları kullanmadığınız sürece bu özellikler kapalıdır.

Null değer atanabilir bir tanıma bağlamında:

  • Başvuru türünün T değişkenini null olmayan bir değerle başlatmanız gerekir ve olabilecek bir değeri nullhiçbir zaman atayamamalısınız.
  • ile T? bir başvuru türünün null değişkenini başlatabilir veya atayabilirsiniznull, ancak başvuruyu kaldırmadan önce değişkeniyle null karşılaştırmalısınız.
  • türünde bir değişkene mT?m!null-forgiving işlecini uyguladığınızda, değişkeni null olmayan olarak kabul edilir.

Derleyici, önceki kuralları kullanarak null atanamayan bir başvuru türü T ile null atanabilir başvuru türü T? arasındaki ayrımları zorlar. T türünde bir değişken ve T? türündeki bir değişken aynı .NET türündedir. Aşağıdaki örnek null atanamayan bir dize ve null atanabilir bir dize bildirir ve ardından null atanamaz bir dizeye değer atamak için null-forgiving işlecini kullanır:

string notNull = "Hello";
string? nullable = default;
notNull = nullable!; // null forgiveness

Değişkenler notNull ve nullable her ikisi de türünü kullanır String . Null atanamaz ve null atanabilir türlerin her ikisi de aynı türü kullandığından, birkaç konumda null atanabilir başvuru türü kullanamazsınız. Genel olarak, null atanabilir başvuru türünü temel sınıf veya uygulanan arabirim olarak kullanamazsınız. Hiçbir nesne oluşturma veya tür testi ifadesinde null atanabilir başvuru türü kullanamazsınız. Üye erişim ifadesinin türü olarak null atanabilir başvuru türünü kullanamazsınız. Aşağıdaki örneklerde şu yapılar gösterilmektedir:

public MyClass : System.Object? // not allowed
{
}

var nullEmpty = System.String?.Empty; // Not allowed
var maybeObject = new object?(); // Not allowed
try
{
    if (thing is string? nullableString) // not allowed
        Console.WriteLine(nullableString);
} catch (Exception? e) // Not Allowed
{
    Console.WriteLine("error");
}

Boş değer atanabilir başvurular ve statik analiz

Önceki bölümdeki örneklerde null atanabilir başvuru türlerinin yapısı gösterilmektedir. Null atanabilir başvuru türleri yeni sınıf türleri değil, mevcut başvuru türlerinde ek açıklamalardır. Derleyici, kodunuzda olası null başvuru hatalarını bulmanıza yardımcı olması için bu ek açıklamaları kullanır. Boş değer atanamayan başvuru türü ile null atanabilir başvuru türü arasında çalışma zamanı farkı yoktur. Derleyici, boş değer atanamayan başvuru türleri için çalışma zamanı denetimi eklemez. Avantajları, derleme zamanı analizindedir. Derleyici, kodunuzdaki olası null hataları bulmanıza ve düzeltmenize yardımcı olacak uyarılar oluşturur. Amacınızı bildirirsiniz ve kodunuz bu amacı ihlal ettiğinde derleyici sizi uyarır.

Önemli

Null atanabilir başvuru ek açıklamaları davranış değişikliklerine neden olmaz, ancak diğer kitaplıklar null atanabilir ve null atanamayan başvuru türleri için farklı çalışma zamanı davranışı oluşturmak için yansıma kullanabilir. Özellikle, Entity Framework Core null atanabilir öznitelikleri okur. Null başvuru isteğe bağlı bir değer, null olmayan başvuru ise gereken bir değer olarak yorumlanır.

Boş değer atanabilir bir bağlamda, derleyici herhangi bir başvuru türündeki değişkenler üzerinde hem null atanabilir hem de null atanamaz statik analiz gerçekleştirir. Derleyici, her başvuru değişkeninin null durumunu not-null veya belki-null olarak izler. Null değer atanamayan bir başvurunun varsayılan durumu null değil. Null atanabilir başvurunun varsayılan durumu belki-null'tır.

Null-durumu null olmadığından, null atanamayan başvuru türlerinin başvurularının geri alınması her zaman güvenli olmalıdır. Bu kuralı zorunlu kılmak için, null olmayan bir başvuru türü null olmayan bir değere başlatılmazsa derleyici uyarılar verir. Yerel değişkenleri bildirdiğiniz yere atamanız gerekir. Her alana bir alan başlatıcıda veya her oluşturucuda null olmayan bir değer atanmalıdır. Derleyici, durumu belki-null olan bir başvuruya null olmayan bir başvuru atandığında uyarılar döndürür. Genellikle, null atanamayan bir başvuru null değildir ve bu değişkenlere başvuruyu kaldırdığınızda hiçbir uyarı verilmez.

Not

Null değer atanamayan bir başvuru türüne belki-null ifadesi atarsanız, derleyici bir uyarı oluşturur. Derleyici daha sonra bu değişken null olmayan bir ifadeye atanana kadar bu değişken için uyarılar oluşturur.

Null atanabilir başvuru türlerini başlatabilir veya atayabilirsiniz null . Bu nedenle statik analiz, bir değişkenin başvurulmadan önce null olmadığını belirlemelidir. Null atanabilir başvuru belki null olarak belirlenirse, bunu null atanamaz bir başvuru değişkenine atamak bir derleyici uyarısı oluşturur. Aşağıdaki sınıf bu uyarıların örneklerini gösterir:

public class ProductDescription
{
    private string shortDescription;
    private string? detailedDescription;

    public ProductDescription() // Warning! shortDescription not initialized.
    {
    }

    public ProductDescription(string productDescription) =>
        this.shortDescription = productDescription;

    public void SetDescriptions(string productDescription, string? details=null)
    {
        shortDescription = productDescription;
        detailedDescription = details;
    }

    public string GetDescription()
    {
        if (detailedDescription.Length == 0) // Warning! dereference possible null
        {
            return shortDescription;
        }
        else
        {
            return $"{shortDescription}\n{detailedDescription}";
        }
    }

    public string FullDescription()
    {
        if (detailedDescription == null)
        {
            return shortDescription;
        }
        else if (detailedDescription.Length > 0) // OK, detailedDescription can't be null.
        {
            return $"{shortDescription}\n{detailedDescription}";
        }
        return shortDescription;
    }
}

Aşağıdaki kod parçacığı, bu sınıfı kullanırken derleyicinin uyarıları nereye yaydığı gösterir:

string shortDescription = default; // Warning! non-nullable set to null;
var product = new ProductDescription(shortDescription); // Warning! static analysis knows shortDescription maybe null.

string description = "widget";
var item = new ProductDescription(description);

item.SetDescriptions(description, "These widgets will do everything.");

Yukarıdaki örneklerde, derleyicinin statik analizinin başvuru değişkenlerinin null durumunu nasıl belirlediğini göstermektedir. Derleyici, çözümlemesini bilgilendirmek için null denetimler ve atamalar için dil kuralları uygular. Derleyici, yöntemlerin veya özelliklerin semantiği hakkında varsayımlarda bulunamaz. Null denetimler gerçekleştiren yöntemleri çağırırsanız, derleyici bu yöntemlerin bir değişkenin null durumunu etkilediğini bilemez. Derleyiciyi bağımsız değişkenlerin semantiği ve dönüş değerleri hakkında bilgilendirmek için API'lerinize öznitelikler ekleyebilirsiniz. .NET kitaplıklarındaki birçok yaygın API'nin bu öznitelikleri vardır. Örneğin, derleyici IsNullOrEmpty'ı null kontrolü olarak doğru bir şekilde yorumlamaktadır. Null durum statik analizine uygulanan öznitelikler hakkında daha fazla bilgi için Null atanabilir öznitelikler makalesine bakın.

Null atanabilir bağlam

Null atanabilir bağlam, derleyicinin null atanabilir başvuru türü ek açıklamalarını nasıl işlediğini ve statik null durum analizi sırasında hangi uyarıları ürettiğini belirler. Anullanabilir bağlam iki bayrak içerir: yorumlama ayarı ve uyarı ayarı.

Hem ek açıklama hem de uyarı ayarları mevcut projeler için varsayılan olarak devre dışı bırakılır. .NET 6'dan (C# 10) başlayarak her iki bayrak da new projeleri için varsayılan olarak etkinleştirilir. Nullable bağlam için iki ayrı işaret kullanılmasının nedeni, nullable başvuru türlerinin getirilmesinden önce var olan büyük projelerin geçişini kolaylaştırmaktır.

Küçük projeler için null atanabilir bağlantı türlerini etkinleştirebilir, uyarıları giderebilir ve devam edebilirsiniz. Ancak, daha büyük projeler ve çok projeli çözümler için bu işlem çok sayıda uyarı oluşturabilir. Null atanabilir başvuru türlerini kullanmaya başladığınızda, bunları dosya bazında etkinleştirmek için pragmaları kullanabilirsiniz. System.NullReferenceException oluşturulmasına karşı koruma sağlayan yeni özellikler, mevcut bir kod tabanında etkinleştirildiğinde kesintiye neden olabilir.

  • Açıkça yazılan tüm başvuru değişkenleri null atanamayan başvuru türleri olarak yorumlanır.
  • Genel türlerdeki class kısıtlamasının anlamı, null atanamayan başvuru türü olacak şekilde değişti.
  • Bu yeni kurallar nedeniyle yeni uyarılar oluşturulur.

Derleyicinin davranışını, boş atanabilir ek açıklama bağlamı belirler. null durum ayarları için dört kombinasyon vardır.

  • her ikisi devre dışı: Kod null'a duyarsız. Devre dışı bırak seçeneği, yeni söz diziminin hatalar yerine uyarılar üretmesi dışında, null atanabilir başvuru türleri etkinleştirilmeden önceki davranışla eşleşir.
    • Nullable uyarıları kapatıldı.
    • Tüm referans türü değişkenleri null atanabilir referans türleridir.
    • ? eki, null atanabilir bir başvuru türü bildirmek için kullanıldığında bir uyarıya neden olur.
    • null forgiving işlecini kullanabilirsiniz, !ancak hiçbir etkisi yoktur.
  • ikisi de etkin: Derleyici, tüm null referans analizi ve tüm dil özellikleri etkin olarak ayarlar.
    • Tüm yeni null değer alabilir uyarılar etkinleştirilir.
    • ? ekini kullanarak null atanabilir bir başvuru türü bildirebilirsiniz.
    • Son eki olmayan ? başvuru türü değişkenleri null olmayan başvuru türleridir.
    • Null forgiving işleci, olası bir başvuru nullkaldırma için uyarıları bastırır.
  • uyarısı etkinleştirildi: Derleyici tüm null analizlerini gerçekleştirir ve kodun nullbaşvuru yapabileceği durumlarda uyarılar yayar.
    • Tüm yeni null değer alabilir uyarılar etkinleştirilir.
    • ? eki, null atanabilir bir başvuru türü bildirmek için kullanıldığında bir uyarıya neden olur.
    • Tüm başvuru türü değişkenlerinin null olması gerekir. Ancak, üyeler sonekiyle bildirilmedikçe, tüm yöntemlerin açılış küme ayracında null-olma durumu yerine ? konumundadır.
    • null forgiving işlecini kullanabilirsiniz. !
  • açıklamalar etkin: Derleyici, kodun null başvurusunu kaldırabileceği veya null olabilecek bir ifadeyi null olamayan bir değişkene atadığınızda uyarı vermez.
    • Tüm yeni null değeri alabilen uyarılar devre dışı bırakıldı.
    • ? ekini kullanarak null atanabilir bir başvuru türü bildirebilirsiniz.
    • Son eki olmayan ? başvuru türü değişkenleri null olmayan başvuru türleridir.
    • null forgiving işlecini kullanabilirsiniz, !ancak hiçbir etkisi yoktur.

.csproj dosyanızdaki öğesini kullanarak bir proje için null atanabilir ek açıklama bağlamını ve null atanabilir uyarı bağlamını <Nullable> ayarlayabilirsiniz. Bu öğe, derleyicinin türlerin null atanabilirliğini nasıl yorumlayıp hangi uyarıları yaydığı yapılandırılır. Aşağıdaki tabloda izin verilebilen değerler gösterilir ve bu değerlerin belirttiği bağlamlar özetler.

Context Gönderme çözümleme uyarıları Atama uyarıları Referans türleri ? ek ! operatör
disable Disabled Disabled Tümü null atanabilir Uyarı oluşturur Etkisi yok
enable Enabled Enabled "? ile bildirilmedikçe null atanamaz" Null olabilen türü bildirir Olası null atama için uyarıları gizler
warnings Enabled Uygulanamaz Tümü null değer atanabilir, ancak metotların açılış küme ayracında üyeler null değilmiş gibi değerlendirilir. Uyarı oluşturur Olası null atama için uyarıları gizler
annotations Disabled Disabled "? ile bildirilmedikçe null atanamaz" Null olabilen türü bildirir Etkisi yok

Devre dışı bırakılmış bir bağlamda derlenen koddaki başvuru türü değişkenleri, null atanabilir-belirsizdir. null sabit bir değer veya belki-null bir değişken, null'lığı önemsemeyen bir değişkene atanabilir. Ancak, bir nullable-oblivious değişkenin varsayılan durumu null olmayan halidir.

Projenize en uygun ayarı seçin:

  • Tanılamaya veya yeni özelliklere göre güncelleştirmek istemediğiniz eski projeler için devre dışı bırak'ı seçin.
  • Uyarıları seçerek kodunuzun nerede System.NullReferenceExceptionfırlatabileceğini belirleyin. Boş değer atanamayan başvuru türlerini etkinleştirmek için kodu değiştirmeden önce bu uyarıları ele alabilirsiniz.
  • Uyarıları etkinleştirmeden önce tasarım amacınızı ifade etmek için ek açıklamaları seçin.
  • Null referans istisnalarına karşı korumak istediğiniz yeni projeler ve aktif projeler için etkinleştir'i seçin.

Örnek:

<Nullable>enable</Nullable>

Bu bayrakları kaynak kodunuzun herhangi bir yerinde ayarlamak için yönergeleri de kullanabilirsiniz. Bu yönergeler en çok büyük bir kod tabanını geçirirken kullanışlıdır.

  • #nullable enable: Açıklama ve uyarı bayraklarını etkinleştir olarak ayarlar.
  • #nullable disable: Ek açıklama ve uyarı bayraklarını devre dışı bırakmak için ayarlar.
  • #nullable restore: Açıklama bayrağını ve uyarı bayrağını proje ayarlarına geri yükler.
  • #nullable disable warnings: Devre dışı bırakmak için uyarı bayrağını ayarlar.
  • #nullable enable warnings: Etkinleştirmek için uyarı bayrağını ayarlar.
  • #nullable restore warnings: Uyarı bayrağını proje ayarlarına geri yükler.
  • #nullable disable annotations: Devre dışı bırakmak için ek açıklama bayrağını ayarlar.
  • #nullable enable annotations: Etkinleştirecek ek açıklama bayrağını ayarlar.
  • #nullable restore annotations: Not bayrağını proje ayarlarına geri yükler.

Herhangi bir kod satırı için aşağıdaki birleşimlerden herhangi birini ayarlayabilirsiniz:

Uyarı bayrağı Açıklama işareti Kullan
proje varsayılan proje varsayılan Varsayılan
enable disable Analiz uyarılarını düzeltme
enable proje varsayılan Analiz uyarılarını düzeltme
proje varsayılan enable Tür ek açıklamaları ekleyin
enable enable Kod zaten taşındı
disable enable Uyarıları düzeltmeden önce koda ek açıklama ekleme
disable disable Geçirilen projeye eski kod ekleme
proje varsayılan disable Nadiren
disable proje varsayılan Nadiren

Bu dokuz birleşim, derleyicinin kodunuz için yaydığı tanılamalar üzerinde ayrıntılı denetim sağlar. Henüz ele almak için hazır olmadığınız daha fazla uyarı görmeden, güncelleştirdiğiniz herhangi bir alanda daha fazla özellik etkinleştirebilirsiniz.

Önemli

Genel null atanabilir bağlam, oluşturulan kod dosyalarına uygulanmaz. Her iki strateji altında da, oluşturulmuş olarak işaretlenmiş tüm kaynak dosyalarda null atanabilir bağlam devre dışı bırakılır. Bu koşul, derleyicinin oluşturulan dosyalarda hiçbir API'ye açıklama eklemediği anlamına gelir. Derleyici, oluşturulan dosyalar için null atanabilir uyarılar üretmez. Bir dosya, aşağıdaki dört yoldan herhangi birinde oluşturuldu olarak işaretlenir:

  1. .editorconfig dosyasında, ilgili dosyaya uygulanan bir bölümde generated_code = true belirleyin.
  2. Dosyanın en üstüne bir açıklama olarak <auto-generated> veya <auto-generated/> ekleyin. Bu açıklamadaki herhangi bir satırda olabilir, ancak açıklama bloğu dosyadaki ilk öğe olmalıdır.
  3. Dosya adını TemporaryGeneratedFile_ ile başlatma
  4. Dosya adını .designer.cs, .generated.cs, .g.cs veya .g.i.cs ile sonlandırın.

Oluşturucular ön işlemci yönergesini #nullable kullanarak kabul edebilir.

Varsayılan olarak, nullable ek açıklama ve uyarı bayrakları devre dışı. Bu varsayılan, mevcut kodunuzun değişiklik yapmadan ve yeni uyarı oluşturmadan derlenmesi anlamına gelir. .NET 6 sürümünden başlayarak, yeni projeler tüm proje şablonlarında <Nullable>enable</Nullable> öğesini içerir ve bu bayrakları enabled olarak ayarlar.

Bu seçenekler, mevcut bir kod tabanını null atanabilir başvuru türlerini kullanmaya uygun hale getirmek için iki farklı strateji sunar.

Null atanabilir bağlamı ayarlama

Null atanabilir bağlamı iki şekilde denetleyebilirsiniz. Proje düzeyinde proje ayarını ekleyin <Nullable>enable</Nullable> . Tek bir C# kaynak dosyasında, null atanabilir bağlamı #nullable enable etkinleştirmek için pragmasını ekleyin. Daha fazla bilgi için bkz. Null atanabilir strateji ayarlama. .NET 6'nın öncesinde, yeni projeler varsayılan <Nullable>disable</Nullable>kullanır. .NET 6 ile başlayarak, yeni projeler proje dosyasında öğesini içerir <Nullable>enable</Nullable> .

Genel Türler

null atanabilir karşılığı T?olarak bir tür parametresi Tkullandığınızda, gerçek tür bağımsız değişkeni değerinin ? nasıl yorumleneceğini belirler. Aşağıdaki genel bildirimi göz önünde bulundurun:

public class Box<T>
{
    public T Contents { get; set; }
}

Tür parametresi bir başvuru türü veya değer türü için dayanabileceğinden, anlamı çağıranın T? hangi tür bağımsız değişkeni sağladığına bağlıdır. Aşağıdaki kurallar, kısıtlama olmadığında nelerin T?T çözümlendiğini açıklar:

  • Tür bağımsız değişkeni null değer atanamayan bir başvuru türüdür. için Box<string>, T is string ve T? is string?— karşılık gelen null atanabilir başvuru türü.
  • Tür bağımsız değişkeni bir değer türüdür. için Box<int>, T ve intT? de intaynı değer türüdür. Tür parametresi kısıtlamaya sahip struct olmadığı sürece ek açıklamanın değer türleri üzerinde hiçbir etkisi yoktur; bu durumda T? (int? anlamına gelir Nullable<T> ).
  • Tür bağımsız değişkeni zaten null atanabilir. için Box<string?>, T ve string?T? hala string?şeklindedir. "Doubly nullable" türüne sahip değilsiniz.

Kısıtlamalar , izin verilen tür bağımsız değişkenlerini kısıtlar. Ayrıca derleyicinin nasıl T kullanılabileceğinin nedenini de verir:

  • where T : class null atanamaz bir başvuru türü gerektirir. Box<string> izin verilir; Box<string?> bir uyarı üretir.
  • where T : class? null atanabilir veya boş değer atanamayan başvuru türüne izin verir. Hem hem de Box<string>Box<string?> izin verilir.
  • where T : struct null atanamaz bir değer türü gerektirir. Box<int> izin verilir; Box<int?> Değil. Bu kısıtlamayla, T? genel ortalamaların Nullable<T>içinde — için Box<int>, T? şeklindedir int?.
  • where T : notnull null atanamaz bir başvuru veya değer türü gerektirir. Box<string> ve Box<int> izin verilir; Box<string?> bir uyarı üretir.
  • where T : BaseType , türünden BaseTypetüretilen null atanamaz bir başvuru türü gerektirir. Null değer atanabilir türetilmiş türlere de izin vermek için ekleyin ? (where T : BaseType?).

Kısıtlamalar, genel tür parametresinin nasıl kullanıldığı konusunda derleyicinin nedenlerine yardımcı olur:

public static T? FirstOrDefault<T>(IEnumerable<T> source)
{
    foreach (T item in source)
    {
        return item;
    }
    return default;
}

public static void RequireNotNull<T>(T value) where T : notnull
{
    ArgumentNullException.ThrowIfNull(value);
}

public static void Generics()
{
    string? first = FirstOrDefault<string>([]);
    Console.WriteLine(first ?? "<empty>");

    RequireNotNull("not null");
}

C# dili belirtimi

Daha fazla bilgi için C# dil belirtimininNull atanabilir başvuru türleri bölümüne bakın.

Ayrıca bkz.

  • Last updated on