預先定義的屬性 (MIDL 3.0)

發行項
07/20/2023

有許多預先定義的自訂屬性，可讓您控制編譯器合成介面 (IID) 的名稱和介面識別碼。這些屬性可讓您在更細微的層級控制類別的版本控制和二進位 API。

如果您是元件開發人員及/或程式庫作者，則您可能會想要使用這些屬性，以確保您的元件在下一個版本中維持二進位穩定的狀態。

如果您是應用程式開發人員，則通常不需要使用這些屬性，因為在修正您的類型之後，您將會重新編譯應用程式。

`[allowforweb]`屬性

如需屬性用法和用途 allowforweb 的詳細資訊，請參閱 AllowForWebAttribute 類別。

`[constructor_name]`屬性

constructor_name屬性會指定包含函式成員之 factory 介面的名稱和 IID。如需 factory 介面的詳細資訊，請參閱合成介面。

注意

處理站介面只適用于具有非預設的函式的密封類別，或使用預設和/或非預設的函式的未密封類別。

在下列範例中，受保護的區塊的函式會放在 IBlockFactory 介面中，而且該介面具有指定的 IID。

[constructor_name("Windows.UI.Xaml.Documents.IBlockFactory", 07110532-4f59-4f3b-9ce5-25784c430507)]
...
unsealed runtimeclass Block : Windows.UI.Xaml.Documents.TextElement
{
    ...
    protected Block();
    ...
}

如此一來，當您的類別描述未以其他方式參考介面，但需要它來執行類別時，MIDL 3.0 編譯器就會會合成並視需要新增介面。

`[contentproperty]`屬性

contentproperty屬性代表ContentPropertyAttribute類別。以下是範例：

// BgLabelControl.idl
namespace BgLabelControlApp
{
    [contentproperty("Content")]
    runtimeclass BgLabelControl : Windows.UI.Xaml.Controls.Control
    {
        BgLabelControl();
        static Windows.UI.Xaml.DependencyProperty LabelProperty{ get; };
        String Label;
        static Windows.UI.Xaml.DependencyProperty ContentProperty{ get; };
        IInspectable Content;
    }
}

`[contract]`屬性

請勿在您自己的 contract api 中使用屬性，它只有內建 Windows api 的意義。

contract屬性會指定 Windows 10 API 合約的名稱和版本 (請參閱使用延伸模組 sdk 進行程式設計) ，其中的屬性型別和（或）成員會先引進 Windows (，因此對於未在 Windows) 中傳遞的 api 而言並不具意義。屬性會採用表單 [contract(ContractName, ContractVersion)] ，而且會出現在其所套用的專案之前。

`[default]`屬性

如果您未指定預設介面，MIDL 3.0 編譯器會選擇第一個實例介面。若要覆寫此選項，請在您想要作為預設介面的介面之前插入 default 屬性。

// Declaring an external interface as the default
runtimeclass C : [default]I { ... }

// Declaring a specific exclusiveto interface as the default.
// This is very unusual.
runtimeclass C
{
    ...

    [default][interface_name(...)]
    {
        ...
    }
}

`[default_interface]`屬性

default_interface屬性是用來強制產生預設介面，而不會產生任何另一個。在下列範例中， StateTriggerBase 不需要預設介面 (，因為它沒有) 的公用非靜態成員，所以它只是存在 default_interface 會產生一個 (名為 IStateTriggerBase) 的屬性。

[default_interface]
unsealed runtimeclass StateTriggerBase
{
    protected void SetActive(Boolean IsActive);
};

`[default_overload]`屬性

注意

函式不支援這個屬性。如果您無法以 arity 來多載您的函式，則可以定義多載的 factory 方法，例如本節最後一個程式碼片段中所示的 CreateFromUri 和 CreateFromStream 範例。

default_overload屬性代表windows.foundation.metadata.defaultoverloadattribute 裝飾類別，表示方法是預設的多載方法。本節將逐步引導您完成屬性的原因和使用指導方針 [default_overload] 。

您可以透過arity自由多載 Windows 執行階段方法。也就是說，您可以定義多個具有相同名稱的方法，只要每個方法都接受不同數目的引數即可。基於可用性的考慮，建議您將新的參數加入至結尾，而且較短的參數清單函式的行為相當於使用 (案例特定的) 預設的遺漏參數的預設值來呼叫較長的參數清單函數。

runtimeclass Widget
{
    void Start();
    void Start(StartMode mode);
    void Start(StartMode mode, Widget parent);
}

在上述範例中，可以使用兩個參數來呼叫 start ，以指定啟動模式和父 widget。如果您省略父小工具，則會預設為 null。如果您省略模式，則會在某些案例特定的預設模式下啟動。

在下一個範例中，我們使用DeviceInformation >createwatcher。

runtimeclass DeviceInformation
{
    static DeviceWatcher CreateWatcher();
    static DeviceWatcher CreateWatcher(DeviceClass deviceClass);
    static DeviceWatcher CreateWatcher(String aqsFilter);
    static DeviceWatcher CreateWatcher(String aqsFilter,
                                       IIterable<String> additionalProperties);
    static DeviceWatcher CreateWatcher(String aqsFilter,
                                       IIterable<String> additionalProperties,
                                       DeviceInformationKind kind);
}

在該範例中，有五個多載，其中大部分都遵循建議的模式，讓每個新的多載成為先前多載的延伸。

如果您決定有多個具有相同參數數目之方法的多載，則會收到編譯器錯誤：

DeviceInformation 的1參數多載只能以 Windows 的方式，指定為預設多載。Windows.foundation.metadata.defaultoverloadattribute 裝飾。

這是因為某些程式設計語言是以動態方式輸入的。 JavaScript 和 Python 有兩個範例。針對這些語言，多載的選取範圍只會考慮參數的數目，而不是其類型。這表示 JavaScript 呼叫 DeviceInformation.createWatcher(v); 不明確—應該將 v 強制轉型為 DeviceClass或字串？

若要解決不明確的問題，您必須將 [default_overload] 屬性套用至其中一個方法。但是您要如何選擇哪一個呢？

您應該選擇預設多載，讓非預設多載的功能仍可透過其他方式（通常是其他多載）使用。

在DeviceInformation. >createwatcher範例中，可以藉由呼叫字串、 iiterable < 字串 >多載，並傳遞空白的屬性清單來取得字串多載的功能。另一方面， DeviceClass多載是建立篩選到DeviceClass之DeviceWatcher的唯一方法。

這會讓 DeviceClass 方法成為明確的優勝者。您可以藉由 [default_overload] 將屬性套用至該多載來表示。

runtimeclass DeviceInformation
{
    static DeviceWatcher CreateWatcher();
    [default_overload]
    static DeviceWatcher CreateWatcher(DeviceClass deviceClass);
    static DeviceWatcher CreateWatcher(String aqsFilter);
    static DeviceWatcher CreateWatcher(String aqsFilter,
                                       IIterable<String> additionalProperties);
    static DeviceWatcher CreateWatcher(String aqsFilter,
                                       IIterable<String> additionalProperties,
                                       DeviceInformationKind kind);
}

如果沒有獲勝者，因為所有衝突的多載都提供了其他多載無法使用的獨特功能？

runtimeclass Widget
{
    static Widget Create(Uri source);
    static Widget Create(IInputStream source);
}

我們的假設 Widget 物件可從 Uri建立，或從輸入資料流程建立。如果我們將一個標記標記為預設多載，則動態類型的程式設計語言會完全無法存取另一個。

若要解決這個問題，請將兩個版本命名為不同的名稱，使其不會超載。

runtimeclass Widget
{
    static Widget CreateFromUri(Uri source);
    static Widget CreateFromStream(IInputStream source);
}

現在這兩種建立模式都適用于所有語言。

另請參閱方法多載和以類別為基礎的投射。

`[interface_name]`屬性

interface_name屬性指定包含類別實例成員之介面的名稱和 IID。根據預設，編譯器會使用針對方法所使用的相同唯一編號演算法來指派介面名稱。

在下列範例中，套用至 runtimeclass 的 interface_name 屬性會指定介面的名稱和 IID，此介面包含類別的所有實例成員，但這些成員未指派給介面。因此， LineHeight、 LineStackingStrategy、 Margin和 >textalignment 是 IBlock 介面的成員。

不過， HorizontalTextAlignment 是 IBlock2 介面的成員，因為 interface_name 包含該成員的屬性。

[interface_name("Windows.UI.Xaml.Documents.IBlock", 4bce0016-dd47-4350-8cb0-e171600ac896)]
...
unsealed runtimeclass Block : Windows.UI.Xaml.Documents.TextElement
{
    ...
    Double LineHeight;
    Windows.UI.Xaml.LineStackingStrategy LineStackingStrategy;
    Windows.UI.Xaml.Thickness Margin;
    Windows.UI.Xaml.TextAlignment TextAlignment;

    [interface_name("Windows.UI.Xaml.Documents.IBlock2", 5ec7bdf3-1333-4a92-8318-6caedc12ef89)]
    {
        Windows.UI.Xaml.TextAlignment HorizontalTextAlignment;
    }
    ...
}

您也可以使用 interface_name 屬性來強制產生介面。在下列範例中， StateTriggerBase 不需要 IStateTriggerBase，而且只是存在 interface_name 造成它產生的屬性。

[interface_name("Windows.UI.Xaml.IStateTriggerBase", 48b20698-af06-466c-8052-93666dde0e49)]
unsealed runtimeclass StateTriggerBase
{
    protected void SetActive(Boolean IsActive);
};

如此一來，當您的類別描述未以其他方式參考介面，但需要它來執行類別時，MIDL 3.0 編譯器就會會合成並視需要新增介面。

如果您使用非必要的 default_interface ，MIDL 3.0 會產生額外的空白介面，並使其成為預設值。

`[method_name]`屬性

每個 Windows 執行階段介面都有對等的應用程式二進位介面 (ABI) 介面。 ABI 介面需要所有成員都有唯一的名稱。 MIDL 3.0 有兩種情況，其中的成員沒有名稱，或沒有唯一的名稱。

函數和
兩個以上的多載方法。

在這些情況下，MIDL 3.0 編譯器會視需要會合成唯一的成員名稱。

根據預設，編譯器會針對 ABI 介面中的相同方法，指派名稱>< 類別、 <classname> 2、 <classname> 3 等的函式方法。換句話說，最小未使用的整數數位尾碼 (從 2) 增加，以使函式方法名稱成為唯一的。

同樣地，針對多載方法，針對一系列多載中的第一個方法 (在 [詞法順序]) 中，編譯器會針對相等的 ABI 介面方法使用原始方法名稱。後續的多載是藉由將最小未使用的整數數位尾碼新增至原始名稱， (從 2) 增加而成為唯一的。

例如，下列 IDL 會宣告 DoWork的三個多載，以及名為 DoWork3的不同方法的兩個多載。

void DoWork(Int32 x);
void DoWork3(Int32 x);
void DoWork(Int32 x, Int32 y);
void DoWork(Int32 x, Int32 y, Int32 z);
void DoWork3(Int32 x, Int32 y);

根據預設 (由於已) 名稱 DoWork3 ，因此編譯器會提供 DoWork 名稱的三個多載

DoWork
DoWork2
DoWork4。

DoWork3不是 DoWork 多載。根據預設，編譯器會提供 DoWork3 名稱的兩個多載

DoWork3
DoWork32。

在 vtable 順序中，函數會顯示為

DoWork
DoWork3
DoWork2
DoWork4
DoWork32

您可以使用 method_name 屬性來覆寫編譯器的預設名稱指派。

在下一個範例中，我們會指示編譯器針對Block預設的函式成員使用 name CreateInstance 。

unsealed runtimeclass Block : Windows.UI.Xaml.Documents.TextElement
{
    ...
    [method_name("CreateInstance")] protected Block();
    ...
}

`[static_name]`屬性

static_name屬性指定包含類別之靜態成員的介面名稱和 IID。

在下一個範例中，套用至 runtimeclass 的 static_name 屬性會指定介面的名稱和 IID，而此介面包含類別的所有靜態成員，但未指派給介面。因此， LineHeightProperty、 LineStackingStrategyProperty、 MarginProperty和 TextAlignmentProperty 是 IBlockStatics 介面的成員。

不過， HorizontalTextAlignmentProperty 是 IBlockStatics2 介面的成員，因為 static_name 包含該成員的屬性。

[static_name("Windows.UI.Xaml.Documents.IBlockStatics", f86a8c34-8d18-4c53-aebd-91e610a5e010)]
...
unsealed runtimeclass Block : Windows.UI.Xaml.Documents.TextElement
{
    ...
    static Windows.UI.Xaml.DependencyProperty LineHeightProperty{ get; };
    static Windows.UI.Xaml.DependencyProperty LineStackingStrategyProperty{ get; };
    static Windows.UI.Xaml.DependencyProperty MarginProperty{ get; };
    static Windows.UI.Xaml.DependencyProperty TextAlignmentProperty{ get; };

    [static_name("Windows.UI.Xaml.Documents.IBlockStatics2", af01a4d6-03e3-4cee-9b02-2bfc308b27a9)]
    {
        static Windows.UI.Xaml.DependencyProperty HorizontalTextAlignmentProperty{ get; };
    }
    ...
}

共用方式為

預先定義的屬性 (MIDL 3.0)

`[allowforweb]`屬性

`[constructor_name]`屬性

`[contentproperty]`屬性

`[contract]`屬性

`[default]`屬性

`[default_interface]`屬性

`[default_overload]`屬性

`[interface_name]`屬性

`[method_name]`屬性

`[static_name]`屬性

意見反應

其他資源

共用方式為

預先定義的屬性 (MIDL 3.0)

[allowforweb]屬性

[constructor_name]屬性

[contentproperty]屬性

[contract]屬性

[default]屬性

[default_interface]屬性

[default_overload]屬性

[interface_name]屬性

[method_name]屬性

[static_name]屬性

意見反應

其他資源

`[allowforweb]`屬性

`[constructor_name]`屬性

`[contentproperty]`屬性

`[contract]`屬性

`[default]`屬性

`[default_interface]`屬性

`[default_overload]`屬性

`[interface_name]`屬性

`[method_name]`屬性

`[static_name]`屬性