C# ön işlemci yönergeleri

Derleyicinin ayrı bir ön işlemcisi olmasa da, bu bölümde açıklanan yönergeler bir tane varmış gibi işlenir. Bunları koşullu derlemede yardımcı olması için kullanırsınız. C ve C++ yönergelerinin aksine, makro oluşturmak için bu yönergeleri kullanamazsınız. Bir satırdaki tek yönerge önişlemci yönergesi olmalıdır.

Boş değer atanabilir bağlam

#nullable Önişlemci yönergesi, null atanabilir ek açıklama bağlamını ve null atanabilir uyarı bağlamını ayarlar. Bu yönerge, null atanabilir ek açıklamaların etkili olup olmadığını ve null atanabilirlik uyarılarının verilip verilmeyeceğini denetler. Her bağlam devre dışı veya etkindir.

Her iki bağlam da öğeye öğe PropertyGroup eklenerek proje düzeyinde (C# kaynak kodunun Nullable dışında) belirtilebilir. yönergesi #nullable ek açıklama ve uyarı bağlamlarını denetler ve proje düzeyi ayarlarından önceliklidir. Yönerge, başka bir yönerge onu geçersiz kılana kadar veya kaynak dosyanın sonuna kadar denetlediğinden bağlamları ayarlar.

Yönergelerin etkisi aşağıdaki gibidir:

• #nullable disable: Null atanabilir ek açıklamayı ve uyarı bağlamlarını devre dışı olarak ayarlar.
• #nullable enable: Null atanabilir ek açıklamayı ve uyarı bağlamlarını etkin olacak şekilde ayarlar.
• #nullable restore: Null atanabilir ek açıklamayı ve uyarı bağlamlarını proje ayarlarına geri yükler.
• #nullable disable annotations: Null atanabilir ek açıklama bağlamını devre dışı olarak ayarlar.
• #nullable enable annotations: Null atanabilir ek açıklama bağlamını etkin olacak şekilde ayarlar.
• #nullable restore annotations: Null atanabilir ek açıklama bağlamını proje ayarlarına geri yükler.
• #nullable disable warnings: Null atanabilir uyarı bağlamını devre dışı olarak ayarlar.
• #nullable enable warnings: Null atanabilir uyarı bağlamını etkin olarak ayarlar.
• #nullable restore warnings: Null atanabilir uyarı bağlamını proje ayarlarına geri yükler.

Koşullu derleme

Koşullu derlemeyi denetlemek için dört önişlemci yönergesi kullanırsınız:

• #if: Kodun yalnızca belirtilen simge tanımlandığında derlendiği koşullu derlemeyi açar.
• #elif: Önceki koşullu derlemeyi kapatır ve belirtilen simgenin tanımlanıp tanımlanmadığını temel alan yeni bir koşullu derleme açar.
• #else: Önceki koşullu derlemeyi kapatır ve önceki belirtilen simge tanımlanmamışsa yeni bir koşullu derleme açar.
• #endif: Önceki koşullu derlemeyi kapatır.

C# derleyicisi, yönergesi ile #endif yönergesi #if arasındaki kodu yalnızca belirtilen simge tanımlandığında veya not işleci kullanıldığında tanımlanmadığında ! derler. C ve C++'ın aksine, bir simgeye sayısal değer atanamaz. #if C# dilindeki deyim Boole değeridir ve yalnızca simgenin tanımlanıp tanımlanmadığını sınar. Örneğin, tanımlandığında DEBUG aşağıdaki kod derlenmiş:

#if DEBUG
    Console.WriteLine("Debug version");
#endif

Aşağıdaki kod tanımlanmadığında MYTEST derlenmiş:

#if !MYTEST
    Console.WriteLine("MYTEST is not defined");
#endif

veya falsedeğerlerini test etmek için bool işleçleri== true (eşitlik) ve != (eşitsizlik) kullanabilirsiniz. true simgenin tanımlandığı anlamına gelir. deyimi #if DEBUG ile aynı anlama sahiptir #if (DEBUG == true). Birden çok simge tanımlanıp tanımlanmadığını && değerlendirmek için (ve), || (veya) ve! (değil) işleçlerini kullanabilirsiniz. Simgeleri ve işleçleri ayraçlarla da gruplandırabilirsiniz.

Aşağıda kodunuzun geriye dönük uyumlu kalırken daha yeni .NET özelliklerinden yararlanmasına olanak tanıyan karmaşık bir yönerge verilmiştir. Örneğin, kodunuzda bir NuGet paketi kullandığınızı, ancak paketin yalnızca .NET 6 ve yukarısını desteklediğini ve .NET Standard 2.0 ve daha yüksek bir sürümü desteklediğini düşünün:

#if (NET6_0_OR_GREATER || NETSTANDARD2_0_OR_GREATER)
    Console.WriteLine("Using .NET 6+ or .NET Standard 2+ code.");
#else
    Console.WriteLine("Using older code that doesn't support the above .NET versions.");
#endif

#if, , , #elif, #endif, #defineve #undef yönergeleriyle #elsebirlikte, bir veya daha fazla simgenin varlığına bağlı olarak kod eklemenize veya hariç tutmanıza olanak tanır. Koşullu derleme, hata ayıklama derlemesi için kod derlerken veya belirli bir yapılandırma için derleme yaparken yararlı olabilir.

Yönerge ile başlayan koşullu yönerge #if , bir yönergeyle #endif açıkça sonlandırılmalıdır. #define bir simge tanımlamanıza olanak tanır. yönergesine #if geçirilen ifade olarak sembolünü kullanarak ifadesi olarak truedeğerlendirilir. DefineConstants derleyici seçeneğiyle bir simge de tanımlayabilirsiniz. ile #undefbir simgenin tanımlarını kaldırabilirsiniz. ile #define oluşturulan bir simgenin kapsamı, içinde tanımlandığı dosyadır. DefineConstants ile veya ile #define tanımladığınız bir simge, aynı ada sahip bir değişkenle çakışmaz. Başka bir ifadeyle, bir değişken adı ön işlemci yönergesine geçirilmemelidir ve bir simge yalnızca önişlemci yönergesi tarafından değerlendirilebilir.

#elif bileşik bir koşullu yönerge oluşturmanıza olanak tanır. yukarıdaki #elif veya herhangi bir önceki #if , isteğe bağlı yönerge ifadesi olarak değerlendirilirse ifade #elif değerlendirilir true. bir #elif ifade olarak değerlendirilirse true, derleyici ile sonraki koşullu yönerge arasındaki #elif tüm kodu değerlendirir. Örneğin:

#define VC7
//...
#if DEBUG
    Console.WriteLine("Debug build");
#elif VC7
    Console.WriteLine("Visual Studio 7");
#endif

#else bileşik bir koşullu yönerge oluşturmanıza olanak tanır; böylece, yukarıdaki #if veya (isteğe bağlı) #elif yönergelerdeki ifadelerden hiçbiri değerini değerlendirmezse true, derleyici ile arasında #else #endiftüm kodu değerlendirir. #endif(#endif) sonrasındaki #elsesonraki önişlemci yönergesi olmalıdır.

#endif , yönergesiyle başlayan bir koşullu yönergenin #if sonunu belirtir.

Derleme sistemi, SDK stilindeki projelerde farklı hedef çerçeveleri temsil eden önceden tanımlanmış ön işlemci sembollerinin de farkındadır. Birden fazla .NET sürümünü hedefleyebilecek uygulamalar oluştururken kullanışlıdır.

Önceden tanımlanmış diğer simgeler ve TRACE sabitlerini içerirDEBUG. kullanarak #defineproje için ayarlanan değerleri geçersiz kılabilirsiniz. Örneğin DEBUG simgesi, derleme yapılandırma özelliklerinize ("Hata Ayıklama" veya "Yayın" modu) bağlı olarak otomatik olarak ayarlanır.

Aşağıdaki örnekte, bir dosyada simge tanımlama MYTEST ve ardından ve DEBUG simgelerinin MYTEST değerlerini test etme adımları gösterilmektedir. Bu örneğin çıktısı, projeyi Hata Ayıklama veya Sürüm yapılandırma modunda oluşturup oluşturmadığınıza bağlıdır.

#define MYTEST
using System;
public class MyClass
{
    static void Main()
    {
#if (DEBUG && !MYTEST)
        Console.WriteLine("DEBUG is defined");
#elif (!DEBUG && MYTEST)
        Console.WriteLine("MYTEST is defined");
#elif (DEBUG && MYTEST)
        Console.WriteLine("DEBUG and MYTEST are defined");
#else
        Console.WriteLine("DEBUG and MYTEST are not defined");
#endif
    }
}

Aşağıdaki örnekte, mümkün olduğunda daha yeni API'leri kullanabilmek için farklı hedef çerçeveleri test etme adımları gösterilmektedir:

public class MyClass
{
    static void Main()
    {
#if NET40
        WebClient _client = new WebClient();
#else
        HttpClient _client = new HttpClient();
#endif
    }
    //...
}

Sembolleri tanımlama

Koşullu derleme sembollerini tanımlamak veya tanımlamak için aşağıdaki iki önişlemci yönergesini kullanırsınız:

• #define: Bir simge tanımlayın.
• #undef: Bir simgenin tanımlarını kaldırın.

Bir simge tanımlamak için kullanırsınız #define . yönergesine geçirilen #if ifade olarak sembolünü kullandığınızda, ifade aşağıdaki örnekte gösterildiği gibi olarak değerlendirilir true:

#define VERBOSE

#if VERBOSE
   Console.WriteLine("Verbose output version");
#endif

Semboller, derleme koşullarını belirtmek için kullanılabilir. simgesi için veya #elifile #if test edebilirsiniz. Koşullu derleme gerçekleştirmek için de ConditionalAttribute kullanabilirsiniz. Simge tanımlayabilirsiniz, ancak simgeye değer atayamazsınız. Önişlemci #define yönergeleri olmayan yönergeleri kullanmadan önce yönergenin dosyada görünmesi gerekir. DefineConstants derleyici seçeneğiyle bir simge de tanımlayabilirsiniz. ile #undefbir simgenin tanımlarını kaldırabilirsiniz.

Bölgeleri tanımlama

Aşağıdaki iki önişlemci yönergesini kullanarak bir ana hat içinde daraltılabilir kod bölgeleri tanımlayabilirsiniz:

• #region: Bir bölge başlatın.
• #endregion: Bir bölgeyi sonlandırma.

#region, kod düzenleyicisinin ana hat özelliğini kullanırken genişletebileceğiniz veya daraltabileceğiniz bir kod bloğu belirtmenize olanak tanır. Daha uzun kod dosyalarında, dosyanın üzerinde çalışmakta olduğunuz bölümüne odaklanabilmeniz için bir veya daha fazla bölgeyi daraltmak veya gizlemek kullanışlıdır. Aşağıdaki örnekte bir bölgenin nasıl tanımlanacağı gösterilmektedir:

#region MyClass definition
public class MyClass
{
    static void Main()
    {
    }
}
#endregion

Bir #region bloğun bir #endregion yönergeyle sonlandırılması gerekir. Blok #region , bir #if blokla örtüşemez. Bununla birlikte, bir #region blok bir #if bloğun içine yerleştirilebilir ve bir #if blok da bir #region bloğun içine iç içe yerleştirilebilir.

Hata ve uyarı bilgileri

Derleyiciye kullanıcı tanımlı derleyici hataları ve uyarıları oluşturmasını ve aşağıdaki yönergeleri kullanarak satır bilgilerini denetlemesini bildirirsiniz:

• #error: Belirtilen iletiyle bir derleyici hatası oluşturun.
• #warning: Belirli bir iletiyle bir derleyici uyarısı oluşturun.
• #line: Derleyici iletileriyle yazdırılan satır numarasını değiştirin.

#error kodunuzda belirli bir konumdan CS1029 kullanıcı tanımlı bir hata oluşturmanıza olanak tanır. Örneğin:

#error Deprecated code in this method.

#warning , kodunuzda belirli bir konumdan CS1030 düzeyinde bir derleyici uyarısı oluşturmanıza olanak tanır. Örneğin:

#warning Deprecated code in this method.

#line derleyicinin satır numaralandırmasını ve (isteğe bağlı olarak) hata ve uyarılar için dosya adı çıkışını değiştirmenize olanak tanır.

Aşağıdaki örnek, satır numaralarıyla ilişkili iki uyarının nasıl rapor yapılacağını gösterir. yönergesi, #line 200 bir sonraki satırın numarasını 200 olarak zorlar (varsayılan değer #6 olmasına rağmen) ve sonraki #line yönergeye kadar dosya adı "Özel" olarak bildirilir. yönergesi #line default , satır numaralandırmasını, önceki yönerge tarafından yeniden numaralandırılmış satırları sayan varsayılan numaralandırmasına döndürür.

class MainClass
{
    static void Main()
    {
#line 200 "Special"
        int i;
        int j;
#line default
        char c;
        float f;
#line hidden // numbering not affected
        string s;
        double d;
    }
}

Derleme aşağıdaki çıkışı oluşturur:

Special(200,13): warning CS0168: The variable 'i' is declared but never used
Special(201,13): warning CS0168: The variable 'j' is declared but never used
MainClass.cs(9,14): warning CS0168: The variable 'c' is declared but never used
MainClass.cs(10,15): warning CS0168: The variable 'f' is declared but never used
MainClass.cs(12,16): warning CS0168: The variable 's' is declared but never used
MainClass.cs(13,16): warning CS0168: The variable 'd' is declared but never used

yönergesi #line , derleme işleminde otomatik, ara bir adımda kullanılabilir. Örneğin, satırlar özgün kaynak kod dosyasından kaldırıldıysa ancak yine de derleyicinin dosyasındaki özgün satır numaralandırmasına göre çıkış oluşturmasını istiyorsanız, satırları kaldırabilir ve ardından ile #lineözgün satır numaralandırmasının benzetimini yapabilirdiniz.

yönergesi #line hidden , hata ayıklayıcıdan ardışık satırları gizler; böylece geliştirici kodda adım attığında, a #line hidden ile sonraki #line yönerge arasındaki tüm satırlar (başka bir #line hidden yönerge olmadığı varsayılarak) üzerine basılır. Bu seçenek, ASP.NET kullanıcı tanımlı ve makine tarafından oluşturulan kod arasında ayrım yapmak için de kullanılabilir. bu özelliğin birincil tüketicisi ASP.NET olsa da, büyük olasılıkla daha fazla kaynak oluşturucu bu özelliği kullanacaktır.

Yönerge #line hidden , hata raporlamadaki dosya adlarını veya satır numaralarını etkilemez. Başka bir ifadeyle, derleyici gizli bir blokta hata bulursa, derleyici hatanın geçerli dosya adını ve satır numarasını bildirir.

yönergesi #line filename , derleyici çıkışında görünmesini istediğiniz dosya adını belirtir. Varsayılan olarak, kaynak kod dosyasının gerçek adı kullanılır. Dosya adı çift tırnak işareti ("") içinde olmalı ve önünde bir satır numarası bulunmalıdır.

C# 10'da başlayarak yönergesinin #line yeni bir biçimini kullanabilirsiniz:

#line (1, 1) - (5, 60) 10 "partial-class.cs"
/*34567*/int b = 0;

Bu formun bileşenleri şunlardır:

• (1, 1): Yönergesini izleyen satırdaki ilk karakterin başlangıç satırı ve sütunu. Bu örnekte, sonraki satır 1. satır, sütun 1 olarak bildirilir.
• (5, 60): İşaretli bölgenin bitiş satırı ve sütunu.
• 10: Yönergenin #line etkili olması için sütun uzaklığı. Bu örnekte, 10. sütun birinci sütun olarak bildirilir. Bildirim burada int b = 0; başlar. Bu alan isteğe bağlıdır. Belirtilmezse, yönerge ilk sütunda geçerlilik kazanır.
• "partial-class.cs": Çıkış dosyasının adı.

Yukarıdaki örnek aşağıdaki uyarıyı oluşturur:

partial-class.cs(1,5,1,6): warning CS0219: The variable 'b' is assigned but its value is never used

Yeniden eşledikten sonra değişkeni, bdosyasının partial-class.csilk satırında, altıncı karakterdedir.

Etki alanına özgü diller (DLL'ler) genellikle kaynak dosyadan oluşturulan C# çıkışına daha iyi bir eşleme sağlamak için bu biçimi kullanır. Bu genişletilmiş #line yönergenin en yaygın kullanımı, oluşturulan bir dosyada görünen uyarıları veya hataları özgün kaynağa yeniden eşlemektir. Örneğin, şu razor sayfasını göz önünde bulundurun:

@page "/"
Time: @DateTime.NowAndThen

özelliği DateTime.Now olarak DateTime.NowAndThenyanlış yazıldı. Bu razor kod parçacığı için oluşturulan C# öğesinde page.g.csaşağıdaki gibi görünür:

  _builder.Add("Time: ");
#line (2, 6) - (2, 27) 15 "page.razor"
  _builder.Add(DateTime.NowAndThen);

Yukarıdaki kod parçacığı için derleyici çıkışı:

page.razor(2, 2, 2, 27)error CS0117: 'DateTime' does not contain a definition for 'NowAndThen'

Satır 2, 6. page.razor sütun metnin @DateTime.NowAndThen başladığı yerdir. Bunu (2, 6) yönergesinde belirtmiş. Bu aralık @DateTime.NowAndThen 2. satır, sütun 27'de biter. Bu, yönergesinde tarafından (2, 27) not edilir. için DateTime.NowAndThen metin 15 page.g.cs. sütunda başlar. Bu, yönergesinde tarafından 15 not edilir. Tüm bağımsız değişkenleri bir araya getirin ve derleyici içindeki konumundaki page.razorhatayı bildirir. Geliştirici, oluşturulan kaynakta değil doğrudan kaynak kodundaki hataya gidebilir.

Bu biçimin diğer örneklerini görmek için örnekler bölümündeki özellik belirtimine bakın.

Pragmalar

#pragma derleyiciye, göründüğü dosyanın derlenmesi için özel yönergeler verir. Yönergeler derleyici tarafından desteklenmelidir. Başka bir deyişle, özel ön işleme yönergeleri oluşturmak için kullanamazsınız #pragma .

• #pragma warning: Uyarıları etkinleştirin veya devre dışı bırakın.
• #pragma checksum: Sağlama toplamı oluşturun.

#pragma pragma-name pragma-arguments

Burada pragma-name tanınan bir pragmanın adı ve pragma-arguments pragma özgü bağımsız değişkenlerdir.

#pragma uyarısı

#pragma warning bazı uyarıları etkinleştirebilir veya devre dışı bırakabilir.

#pragma warning disable warning-list
#pragma warning restore warning-list

Burada warning-list , uyarı numaralarının virgülle ayrılmış listesidir. "CS" ön eki isteğe bağlıdır. Hiçbir uyarı numarası belirtilmediğinde, disable tüm uyarıları devre dışı bırakır ve restore tüm uyarıları etkinleştirir.

, disable kaynak dosyanın bir sonraki satırından başlayarak geçerlilik kazanır. Uyarı, öğesini izleyen satıra restoregeri yüklenir. Dosyada yoksa restore , uyarılar aynı derlemedeki sonraki dosyaların ilk satırında varsayılan durumlarına geri yüklenir.

// pragma_warning.cs
using System;

#pragma warning disable 414, CS3021
[CLSCompliant(false)]
public class C
{
    int i = 1;
    static void Main()
    {
    }
}
#pragma warning restore CS3021
[CLSCompliant(false)]  // CS3021
public class D
{
    int i = 1;
    public static void F()
    {
    }
}

#pragma sağlama toplamı

ASP.NET sayfalarında hata ayıklamaya yardımcı olması için kaynak dosyalar için sağlama toplamları oluşturur.

#pragma checksum "filename" "{guid}" "checksum bytes"

Burada "filename" , değişikliklerin veya güncelleştirmelerin izlenmesini gerektiren dosyanın adı, "{guid}" karma algoritmasının Genel Benzersiz Tanımlayıcısı (GUID) ve "checksum_bytes" sağlama toplamının baytlarını temsil eden onaltılık basamak dizesidir. Çift sayıda onaltılık basamak olmalıdır. Tek sayıda basamak derleme zamanı uyarısına neden olur ve yönergesi yoksayılır.

Visual Studio hata ayıklayıcısı, her zaman doğru kaynağı bulduğundan emin olmak için bir sağlama toplamı kullanır. Derleyici bir kaynak dosyanın sağlama toplamını hesaplar ve ardından çıkışı program veritabanı (PDB) dosyasına yayar. Hata ayıklayıcısı daha sonra PDB'yi kullanarak kaynak dosya için hesaplayan sağlama toplamıyla karşılaştırır.

Hesaplanan sağlama toplamı .aspx dosyası yerine oluşturulan kaynak dosyaya yönelik olduğundan bu çözüm ASP.NET projelerde çalışmaz. Bu sorunu gidermek için ASP.NET #pragma checksum sayfaları için sağlama toplamı desteği sağlar.

Visual C# içinde bir ASP.NET projesi oluşturduğunuzda, oluşturulan kaynak dosya kaynağın oluşturulduğu .aspx dosyası için bir sağlama toplamı içerir. Derleyici daha sonra bu bilgileri PDB dosyasına yazar.

Derleyici dosyada bir #pragma checksum yönerge bulamazsa sağlama toplamını hesaplar ve değeri PDB dosyasına yazar.

class TestClass
{
    static int Main()
    {
        #pragma checksum "file.cs" "{406EA660-64CF-4C82-B6F0-42D48172A799}" "ab007f1d23d9" // New checksum
    }
}