Részleges tag (C#-referencia)

A részleges tagnak van egy deklaráló nyilatkozata , és gyakran egy végrehajtási nyilatkozata. A deklarálási deklaráció nem tartalmaz törzset. A végrehajtási nyilatkozat tartalmazza a tag szervét. A részleges tagok lehetővé teszik az osztálytervezők számára, hogy olyan taghogokat biztosítsanak, amelyek olyan eszközök használatával valósíthatók meg, mint a forrásgenerátorok. A részleges típusok és tagok lehetővé teszik az emberi fejlesztők számára egy típus egy részének írását, míg az eszközök a típus más részeit is megírják. Ha a fejlesztő nem ad meg opcionális implementációs deklarációt, a fordító fordításkor eltávolíthatja a deklarációs deklarációt. A részleges tagokra a következő feltételek vonatkoznak:

• A deklarációknak a környezeti kulcsszó részlegesével kell kezdődniük.
• A részleges típus mindkét részén meg kell egyeznie az aláírásoknak.

A partial kulcsszó nem engedélyezett konstruktorokon, véglegesítőkön, túlterhelt operátorokon vagy eseménydeklarációkon. A C# 13 partial előtt nem volt engedélyezve a tulajdonságok vagy indexelők számára.

Az alábbi esetekben nem szükséges részleges metódus implementálási deklarációval rendelkeznie:

• Nem rendelkezik akadálymentességi módosítókkal (az alapértelmezettet privateis beleértve).
• A visszaadott érték void.
• out Nincsenek paraméterei.
• Nem rendelkezik az alábbi módosítók virtualegyikével sem, newoverridesealedexternsem pedig .

Minden olyan tagnak, aki nem felel meg az összes korlátozásnak (például public virtual partial void metódusnak), rendelkeznie kell egy implementációval. A részleges tulajdonságoknak és indexelőknek implementációval kell rendelkezniük.

Az alábbi példa egy olyan részleges módszert mutat be, amely megfelel az előző korlátozásoknak:

partial class MyPartialClass
{
    // Declaring definition
    partial void OnSomethingHappened(string s);
}

// This part can be in a separate file.
partial class MyPartialClass
{
    // Comment out this method and the program
    // will still compile.
    partial void OnSomethingHappened(string s) =>
        Console.WriteLine($"Something happened: {s}");
}

A részleges tagok a forrásgenerátorokkal együtt is hasznosak lehetnek. Egy regex például a következő mintával határozható meg:

public partial class RegExSourceGenerator
{
    [GeneratedRegex("cat|dog", RegexOptions.IgnoreCase, "en-US")]
    private static partial Regex CatOrDogGeneratedRegex();

    private static void EvaluateText(string text)
    {
        if (CatOrDogGeneratedRegex().IsMatch(text))
        {
            // Take action with matching text
        }
    }
}

Az előző példa egy részleges módszert mutat be, amely végrehajtási deklarációval rendelkezik. A build részeként a Reguláris kifejezés forrásgenerátora létrehozza a végrehajtási deklarációt.

Az alábbi példa egy deklarációs deklarációt és egy végrehajtási deklarációt mutat be egy osztályhoz. Mivel a metódus visszatérési típusa nem void ( stringez ) és a hozzáférése, publica metódusnak implementálási deklarációval kell rendelkeznie:

// Declaring declaration
public partial class PartialExamples
{
    /// <summary>
    /// Gets or sets the number of elements that the List can contain.
    /// </summary>
    public partial int Capacity { get; set; }

    /// <summary>
    /// Gets or sets the element at the specified index.
    /// </summary>
    /// <param name="index">The index</param>
    /// <returns>The string stored at that index</returns>
    public partial string this[int index] { get; set; }

    public partial string? TryGetAt(int index);
}

public partial class PartialExamples
{
    private List<string> _items = [
        "one",
        "two",
        "three",
        "four",
        "five"
        ];

    // Implementing declaration

    /// <summary>
    /// Gets or sets the number of elements that the List can contain.
    /// </summary>
    /// <remarks>
    /// If the value is less than the current capacity, the list will shrink to the
    /// new value. If the value is negative, the list isn't modified.
    /// </remarks>
    public partial int Capacity
    {
        get => _items.Count;
        set
        {
            if ((value != _items.Count) && (value >= 0))
            {
                _items.Capacity = value;
            }
        }
    }

    public partial string this[int index]
    {
        get => _items[index];
        set => _items[index] = value;
    }

    /// <summary>
    /// Gets the element at the specified index.
    /// </summary>
    /// <param name="index">The index</param>
    /// <returns>The string stored at that index, or null if out of bounds</returns>
    public partial string? TryGetAt(int index)
    {
        if (index < _items.Count)
        {
            return _items[index];
        }
        return null;
    }
}

Az előző példa a két deklaráció kombinálásának szabályait mutatja be:

• Aláírási egyezések: Általában a deklarálási és végrehajtási nyilatkozatok aláírásainak egyeznie kell. Ez magában foglalja a metódusok, tulajdonságok, indexelők és egyes tartozékok akadálymentességi módosítóit. Az összes paraméter paramétertípusát és ref-típusú módosítóit tartalmazza. A visszatérési típusnak és a ref típusú módosítónak meg kell egyeznie. A tagneveknek egyeznie kell. Néhány szabály azonban rugalmas:
  • A deklarálási és végrehajtási deklarációk különböző null értékű széljegyzet-beállításokkal rendelkezhetnek. Ez azt jelenti, hogy az egyik lehet null értékű, a másik pedig engedélyezve.
  • Az olyan nullabilitási különbségek, amelyek nem foglalnak magukban kötelező nullitást , figyelmeztetést eredményeznek.
  • Az alapértelmezett paraméterértékek nem egyeznek. A fordító figyelmeztetést ad ki, ha egy metódus vagy indexelő implementálási deklarációja alapértelmezett paraméterértéket deklarál.
  • A fordító figyelmeztetést ad ki, ha a paraméternevek nem egyeznek. A kibocsátott IL tartalmazza a deklaráló deklaráció paraméterneveit.
• Dokumentációs megjegyzések: A dokumentáció megjegyzései bármelyik deklarációból is szerepelhetnek. Ha mind a deklarálási, mind a végrehajtási nyilatkozat dokumentációs megjegyzéseket tartalmaz, a végrehajtási nyilatkozatban szereplő megjegyzések is szerepelnek. Az előző példában a dokumentáció megjegyzései a következők:
  • Capacity A tulajdonság esetében a megjegyzések a végrehajtási nyilatkozatból származnak. A végrehajtási deklarációs megjegyzések akkor használatosak, ha mindkét nyilatkozat megjegyzésekkel rendelkezik /// .
  • Az indexelő esetében a megjegyzések a deklarálási nyilatkozatból származnak. A végrehajtási deklaráció nem tartalmaz megjegyzéseket /// .
  • A megjegyzések a TryGetAtvégrehajtási nyilatkozatból származnak. A deklaráló deklaráció nem tartalmaz megjegyzéseket /// .
  • A létrehozott XML dokumentációs megjegyzéseket fűz az összes public taghoz.
• A legtöbb attribútumdeklaráció kombinálva van. Az összes hívóinformációs attribútum azonban a következővel van definiálva AllowMultiple=false: . A fordító felismeri a deklarálási deklaráció hívóinformációs attribútumát. A rendszer figyelmen kívül hagyja a végrehajtási deklaráció összes hívóinformációs attribútumát. A fordító figyelmeztetést ad ki, ha hívóinformációs attribútumokat ad hozzá a implementálási deklarációhoz.

Lásd még

• részleges típus