الموجّهة using وفضاءات الأسماء في C#: الأسماء المستعارة وusing static وglobal using

لكل نوع في .NET اسم كامل مكوّن من فضاء أسماء واسم النوع: System.Console وSystem.Collections.Generic.List<T> وSystem.Text.StringBuilder. تجمع فضاءات الأسماء الأنواع المترابطة وتمنع تعارض الأسماء، فيتعايش صنفك Order أو Timer مع أصناف تحمل الاسم نفسه من المكتبات. وتستورد الموجّهة using في أعلى الملف فضاء أسماء كي تستخدم الأسماء القصيرة.

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. إن أبلغ المترجم أن نوعًا أو فضاء أسماء "could not be found (are you missing a using directive or an assembly reference?)"، وهو الخطأ CS0246، فإما أن سطر using مفقود أو أن الحزمة غير مُشار إليها.

التصريح بفضاءات أسمائك

ضع الأنواع داخل كتلة 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.، لأن الأسماء يُبحث عنها أولًا في فضاءات الأسماء المحيطة.

الأعراف: ابدأ باسم الشركة أو المنتج (Contoso.Payments)، ثم الميزة أو الطبقة، وطابق بنية المجلدات (Contoso.Payments/Refunds/RefundService.cs يحتوي Contoso.Payments.Refunds). لا تسمِّ صنفًا باسم فضاء أسمائه أبدًا (Shop.Shop)، فهذا يفرض تأهيلًا مربكًا في كل مكان.

الأسماء المستعارة

تمنح using Name = Namespace.Type; نوعًا (أو فضاء أسماء) اسمًا محليًا. حالتان تستدعيانها: تقصير نوع عام طويل، وحل تعارض.

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 وما بعده يمكن للاسم المستعار أن يسمّي أي نوع، بما في ذلك الصفوف والمصفوفات: using Point = (int X, int Y);.

المراجع الملتبسة (CS0104)

حين يحتوي فضاءا أسماء مستوردان على نوع بالاسم نفسه يكون استخدام الاسم القصير خطأ. الحالة التقليدية هي 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

إن عرّف فضاء أسمائك نوعًا اسمه 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 أيضًا مع التعدادات (using static System.DayOfWeek; تتيح لك كتابة Monday) ومع أصنافك الساكنة. استخدمها حيث تبقى الأسماء القصيرة غير ملتبسة؛ فـ WriteLine وحدها في ملف كبير قد تترك القارئ يتساءل أي كاتب هو.

global using وفضاءات الأسماء على مستوى الملف (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 (الافتراضي في القوالب الجديدة) يحصل مشروع الكونسول على System وSystem.Collections.Generic وSystem.IO وSystem.Linq وSystem.Net.Http وSystem.Threading وSystem.Threading.Tasks؛ وتحصل مشاريع الويب على فضاءات أسماء ASP.NET Core أيضًا. لهذا تبدأ ملفات Program.cs الحديثة بالشيفرة مباشرة.

ويصرّح فضاء الأسماء على مستوى الملف بفضاء الأسماء للملف كله بفاصلة منقوطة بدل كتلة، فيوفّر مستوى واحدًا من الإزاحة:

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

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

لا يمكن أن يحتوي الملف إلا على فضاء أسماء واحد على مستوى الملف، ولا يمكن خلطه بفضاءات أسماء الكتل في الملف نفسه. تستخدم المشاريع الأقدم وسكربتات Unity والشيفرة التي تستهدف .NET Framework شكل الكتلة المعروض سابقًا.

أين توضع موجّهات using، والعبارة using

يجب أن تأتي موجّهات using قبل أي تصريح بفضاء أسماء أو نوع في الملف (وglobal usings قبل كل شيء آخر). ويمكن أيضًا وضعها داخل كتلة فضاء أسماء، فتنطبق هناك فقط؛ تختلف أدلة الأسلوب في ذلك، ومعظم شيفرة .NET تبقيها في أعلى الملف.

للكلمة using مهمة ثانية لا علاقة لها بالأولى داخل الدوال: العبارة using using (var file = File.OpenRead(path)) { ... } تستدعي Dispose على الكائن حين تنتهي الكتلة، فتغلق الملفات والاتصالات. تشترك معها في الكلمة ولا شيء غير ذلك. راجع صفحة العبارة using.