C# using ו-namespace: כינויים, using static ו-global using

לכל טיפוס ב-.NET יש שם מלא שמורכב מ-namespace ומשם הטיפוס: System.Console, System.Collections.Generic.List<T>, System.Text.StringBuilder. namespaces מקבצים טיפוסים קשורים ומונעים התנגשויות שמות, כך שהמחלקה Order או Timer שלכם יכולה להתקיים לצד מחלקות באותו שם מספריות. הנחיית using בראש קובץ מייבאת namespace כדי שתוכלו להשתמש בשמות הקצרים.

using System;
using System.Collections.Generic;
using System.Text;

class Program
{
    static void Main()
    {
        // With the using directives:
        var cart = new List<string> { "tea", "honey" };
        var sb = new StringBuilder();
        sb.Append("Cart: ").Append(string.Join(", ", cart));
        Console.WriteLine(sb.ToString());

        // The same thing with fully qualified names, no directives needed:
        var cart2 = new System.Collections.Generic.List<string> { "milk" };
        System.Console.WriteLine(cart2.Count);
    }
}

פלט:

Cart: tea, honey
1

הנחיית using משפיעה רק על שמות בזמן קומפילציה. היא לא טוענת ספרייה ולא מוסיפה קוד לתוכנית; אילו ספריות זמינות נקבע לפי ההפניות של הפרויקט וחבילות ה-NuGet שלו. אם הקומפיילר מדווח שטיפוס או namespace "could not be found (are you missing a using directive or an assembly reference?)", שגיאה CS0246, אז או ששורת ה-using חסרה או שאין הפניה לחבילה.

הצהרה על namespaces משלכם

שימו טיפוסים בתוך בלוק namespace. אפשר לקנן namespaces, לכתוב אותם עם נקודות, ואותו namespace יכול להתפרס על פני קבצים רבים.

using System;

namespace Shop.Billing
{
    class Invoice
    {
        public decimal Amount = 120.00m;
    }
}

namespace Shop.Shipping
{
    class Invoice   // same name, different namespace: no clash
    {
        public string Carrier = "DHL";
    }
}

namespace Shop
{
    class Program
    {
        static void Main()
        {
            var bill = new Billing.Invoice();        // relative to Shop
            var label = new Shop.Shipping.Invoice(); // full name
            Console.WriteLine($"{bill.Amount:F2} via {label.Carrier}");
            Console.WriteLine(typeof(Billing.Invoice).FullName);
        }
    }
}

פלט:

120.00 via DHL
Shop.Billing.Invoice

namespace Shop.Billing { } הוא קיצור של namespace Shop { namespace Billing { } }. קוד בתוך Shop יכול להתייחס ל-Billing.Invoice בלי הקידומת Shop., כי שמות מחופשים קודם ב-namespaces העוטפים.

מוסכמות: התחילו בחברה או במוצר (Contoso.Payments), אחר כך התכונה או השכבה, והתאימו למבנה התיקיות (Contoso.Payments/Refunds/RefundService.cs מכיל את Contoso.Payments.Refunds). לעולם אל תקראו למחלקה באותו שם כמו ה-namespace שלה (Shop.Shop), כי זה מכריח ציון שם מלא ומסורבל בכל מקום.

כינויים (aliases)

using Name = Namespace.Type; נותן לטיפוס (או ל-namespace) שם מקומי. יש שני מצבים שבהם זה שימושי: קיצור של טיפוס גנרי ארוך, ופתרון התנגשות.

using System;
using System.Collections.Generic;
using PriceTable = System.Collections.Generic.Dictionary<string, decimal>;
using Col = System.Collections.Generic;

class Program
{
    static void Main()
    {
        var prices = new PriceTable
        {
            ["espresso"] = 2.40m,
            ["latte"] = 3.60m
        };
        Console.WriteLine($"latte: {prices["latte"]:F2}");

        var queue = new Col.Queue<string>();
        queue.Enqueue("order 17");
        Console.WriteLine(queue.Peek());
    }
}

פלט:

latte: 3.60
order 17

כינויים חלים רק על הקובץ שבו הם מוצהרים (אלא אם הם global, בהמשך). ב-C# 12 ואילך כינוי יכול לתת שם לכל טיפוס, כולל tuples ומערכים: using Point = (int X, int Y);.

הפניות עמומות (CS0104)

כששני namespaces מיובאים מכילים טיפוס באותו שם, שימוש בשם הקצר הוא שגיאה. המקרה הקלאסי הוא Timer, שקיים ב-System.Threading, ב-System.Timers וגם (באפליקציות דסקטופ) ב-System.Windows.Forms:

using System.Threading;
using System.Timers;

var t = new Timer(1000);
// error CS0104: 'Timer' is an ambiguous reference between
// 'System.Timers.Timer' and 'System.Threading.Timer'

שלושה תיקונים, מהמקומי ביותר לפחות מקומי: לכתוב את השם המלא (new System.Timers.Timer(1000)), להוסיף כינוי שאומר לאיזה מהם הכוונה, או להסיר את ההנחיה שלא צריך.

using System;
using System.Threading;
using System.Timers;
using Timer = System.Timers.Timer;   // "Timer" now means this one

class Program
{
    static void Main()
    {
        var timer = new Timer(250);
        Console.WriteLine(timer.Interval);
        Console.WriteLine(timer.GetType().FullName);

        // The other Timer is still reachable by its full name:
        Console.WriteLine(typeof(System.Threading.Timer).FullName);
        timer.Dispose();
    }
}

פלט:

250
System.Timers.Timer
System.Threading.Timer

אם ה-namespace שלכם מגדיר טיפוס בשם System או Console, הקידומת global:: מכריחה חיפוש מהשורש: global::System.Console.WriteLine("hi");. קוד שנוצר אוטומטית משתמש בה בכל מקום מהסיבה הזו.

using static

using static מייבא את האיברים הסטטיים של טיפוס אחד, כך שאפשר לקרוא להם בלי שם הטיפוס. זה מתאים לקוד שקורא שוב ושוב לאותה מחלקה, כמו Math:

using System;
using static System.Math;
using static System.Console;

class Program
{
    static void Main()
    {
        double radius = 3;
        double area = PI * Pow(radius, 2);
        WriteLine($"Area: {area:F2}");
        WriteLine($"Hypotenuse: {Sqrt(3 * 3 + 4 * 4)}");
        WriteLine(Max(17, 42));
    }
}

פלט:

Area: 28.27
Hypotenuse: 5
42

using static עובד גם עם enums (using static System.DayOfWeek; מאפשר לכתוב Monday) ועם מחלקות סטטיות משלכם. השתמשו בו כשהשמות הקצרים נשארים חד-משמעיים; WriteLine לבדו בקובץ גדול עלול להשאיר את הקוראים תוהים על איזה כותב מדובר.

global using ו-namespaces ברמת קובץ (C# 10)

שתי תכונות של C# 10 מקצרות את הקוד החוזר בראש הקבצים. global using חל על כל קובץ בפרויקט, ובדרך כלל שומרים אותו בקובץ אחד כמו GlobalUsings.cs:

// GlobalUsings.cs, C# 10 and later
global using System;
global using System.Collections.Generic;
global using System.Linq;
global using Money = System.Decimal;

פרויקטי SDK על .NET 6 ואילך יכולים ליצור אותם בשבילכם. עם <ImplicitUsings>enable</ImplicitUsings> בקובץ ה-.csproj (ברירת המחדל בתבניות חדשות), פרויקט console מקבל את System, System.Collections.Generic, System.IO, System.Linq, System.Net.Http, System.Threading ו-System.Threading.Tasks; פרויקטי web מקבלים גם namespaces של ASP.NET Core. לכן קבצי Program.cs מודרניים מתחילים ישר בקוד.

namespace ברמת קובץ (file-scoped) מצהיר על ה-namespace לכל הקובץ עם נקודה-פסיק במקום בלוק, וחוסך רמת הזחה אחת:

// C# 10 and later
namespace Shop.Billing;

public class Invoice
{
    public decimal Amount { get; set; }
}

בקובץ יכול להיות רק namespace אחד ברמת קובץ, ואי אפשר לערבב אותו עם namespaces בצורת בלוק באותו קובץ. פרויקטים ישנים, סקריפטים של Unity וקוד שמכוון ל-.NET Framework משתמשים בצורת הבלוק שהוצגה קודם.

איפה שמים הנחיות using, והוראת using

הנחיות using חייבות להופיע לפני כל הצהרה על namespace או על טיפוס בקובץ (ו-global usings לפני כל השאר). אפשר גם לשים אותן בתוך בלוק namespace, ואז הן חלות רק שם; מדריכי הסגנון חלוקים בעניין, ורוב הקוד ב-.NET שומר אותן בראש הקובץ.

למילת המפתח using יש תפקיד שני, שאין לו קשר, בתוך מתודות: הוראת using using (var file = File.OpenRead(path)) { ... } קוראת ל-Dispose על האובייקט כשהבלוק מסתיים, וכך סוגרת קבצים וחיבורים. היא חולקת את מילת המפתח ותו לא. ראו את הדף על הוראת using.