[Из песочницы] .NET-обёртки нативных библиотек на C++/CLI22.12.2016 18:04

Идея этого перевода появилась после статьи «Unmanaged C++ library в .NET. Полная интеграция». Перевод занял больше времени, чем ожидалось, но, возможно, подход, показанный здесь, также будет полезен сообществу.

1. Создание обёрток для нативных библиотек
   
   1. Прежде, чем начать
      
      1. Отдельная DLL или интеграция в проект нативной библиотеки?
      2. Какая часть нативной библиотеки должна быть доступна через обёртку?
   2. Взаимодействие языков
   3. Создание обёрток для классов
      
      1. Отображение нативных типов на типы, соответствующие CLS
      2. Отображение исключений C++ на управляемые исключения
      3. Отображение управляемых массивов на нативные типы
      4. Отображение других непримитивных типов
      5. Поддержка наследования и виртуальных методов
   4. Общие рекомендации
      
      1. Упростите обёртки с самого начала
      2. Учитывайте философию .NET
   5. Заключение

Прежде, чем начать

Отдельная DLL или интеграция в проект нативной библиотеки?

Тем не менее, включение обёрток в оборачиваемую библиотеку как правило не несёт пользы. Чтобы лучше понять почему, следует отдельно рассмотреть сборку статической библиотеки и DLL.

Как бы странно это не звучало, но управляемые типы можно включить в статическую библиотеку. Однако это легко может повлечь за собой проблемы идентичности типов. Сборка, в которой определён тип, является частью его идентификатора. Таким образом, CLR может различить два типа из разных сборок, даже если имена типов совпадают. Если два разных проекта использую один и тот же управляемый тип из статической библиотеки, то этот тип будет скомпонован в обе сборки. Так как сборка является частью идентификатора типа, то получится два типа с разными идентификаторами, хотя они и были определены в одной статической библиотеке.

Интеграция управляемых типов в нативную DLL также не рекомендуется, так как загрузка библиотеки потребует CLR 2.0 во времени загрузки. Даже если приложение, использующее библиотеку, обращается только к нативному коду, для загрузки библиотеки потребуется, чтобы на компьютере была установлена CLR 2.0, и чтобы приложение не загружало более раннюю версию CLR.

Какая часть нативной библиотеки должна быть доступна через обёртку?

Когда вы приступаете к созданию обёртки для нативной библиотеки, задача кажется очевидной — у вас уже есть существующая библиотека и управляемое API должно принести её функциональность в мир управляемого кода.

Для большинства проектов такого общего описания совершенно недостаточно. Без более чёткого понимания проблемы вы, вероятно, напишете по обёртке для каждого нативного класса C++ библиотеки. Если библиотека содержит больше одной единственной центральной абстракции, то зачастую не стоит создавать обёртки один-к-одному с нативным кодом. Это заставит вас решать проблемы, не связанные с вашей конкретной задачей, а также породит много неиспользованного кода.

Чтобы лучше описать задачу, подумайте над проблемой в целом. Чтобы сформулировать задачу более чётко, вам надо ответить на два вопроса:

• Какое подмножество нативного API нужно управляемому коду?
• Как управляемый код будет использовать различные части нативного API?

namespace NativeLib
{
    class CryptoAlgorithm
    {
    public:
        virtual void Encrypt(/* ... пока что аргументы можно опустить ... */) = 0;
        virtual void Decrypt(/* ... пока что аргументы можно опустить ... */) = 0;
    };

    class SampleCipher : public CryptoAlgorithm
    {
        /* ... пока что реализацию можно опустить ... */
    };

    class AnotherCipherAlgorithm : public CryptoAlgorithm
    {
        /* ... пока что реализацию можно опустить ... */
    };
}

• создавать и использовать экземпляр SampleCipher;
• создавать и использовать экземпляр AnotherCipherAlgorithm;
• наследовать классы от CryptoAlgorithm, SampleCipher или AnotherCipherAlgorithm и переопределять Encrypt или Decrypt.

Однако весьма вероятно, что обёртка нужна только для одного или двух алгоритмов. Если обёртка для этого API не будет поддерживать наследование, то её создание упрощается. С таким упрощением вам не придётся создавать обёртку для абстрактного класса CryptoAlgorithm. С виртуальными методами Encrypt и Decrypt можно будет работать так же, как и с любыми другими. Чтобы дать понять, что вы не хотите поддерживать наследование, достаточно объявить обёртки для SampleCipher и AnotherCipherAlgorithm как sealed классы.

Взаимодействие языков

Чтобы чётко определить, смогут ли языки взаимодействовать между собой, CLI содержит Common Language Specification (CLS). CLS — это контракт между разработчиками, использующими языки .NET, и разработчиками библиотек, которые можно использовать из разных языков. CLS задаёт минимальный набор возможностей, который обязан поддерживать каждый язык .NET. Чтобы библиотеку можно было использовать из любого языка .NET, соответствующего CLS, возможности языка, используемые в публичном интерфейсе библиотеки, должны быть ограничены возможностями CLS. Под публичным интерфейсом библиотеки понимаются все типы с видимостью public, определённые в сборке, и все члены таких типов с видимостью public, public protected или protected.

Можно использовать атрибут CLSCompliantAttribute, чтобы обозначить тип или его член как соответствующий CLS. По умолчанию, не помеченные этим атрибутом типы считаются не соответствующими CLS. Если вы примените этот атрибут на уровне сборки, то по умолчанию все типы будут считаться соответствующими CLS. Следующий пример показывает, как применять этот атрибут к сборкам и типам:

[assembly: CLSCompliant(true)];  // типы с видимостью public соответствуют CLS, если не указано иное

namespace ManagedWrapper
{
    public ref class SampleCipher sealed
    {
        // ...
    };

    [CLSCompliant(false)] // этот класс явно помечен как не соответствующий CLS
    public ref class AnotherCipherAlgorithm sealed
    {
        // ...
    };
}

В Framework Class Library (FCL) также используется атрибут CLSCompliant. mscorlib и большинство других библиотек FCL применяют атрибут [CLSCompliant (true)] на уровне сборки и помечают типы, не соответствующие CLS, атрибутом [CLSCompliant (false)].

Учтите, что следующие примитивные типы в mscorlib помечены как несоответствующие CLS: System: SByte, System: UInt16, System: UInt32 и System: UInt64. Эти типы (или эквивалентные им имена типов char, unsigned short, unsigned int, unsigned long и unsigned long long в C++) нельзя использовать в сигнатурах членов типов, которые считаются соответствующими CLS.

Если тип считается соответствующим CLS, то все его члены также считаются таковыми, если явно не указано обратного. Пример:

using namespace System;

[assembly: CLSCompliant(true)]; // типы с видимостью public соответствуют CLS, если не указано иное

namespace ManagedWrapper
{
    public ref class SampleCipher sealed // SampleCipher соответствует CLS из-за атрибута сборки
    {
    public:
        void M1(int);

        // M2 помечен как несоответствующий CLS, потому что тип одного из его аргументов не соответствует CLS
        [CLSCompliant(false)]
        void M2(unsigned int);
    };
}

• Имена типов и их членов должны быть различимы в языках с регистро-независимыми идентификаторами (правило 4).
• Глобальные статические (static) поля и методы не совместимы с CLS (правило 36).
• Пользовательские атрибуты должны содержать поля только следующих типов: System: Type, System: String, System: Char, System: Boolean, System: Int[16×32|64], System: Single и System: Double (правило 34).
• Объекты исключений должны иметь тип System: Exception или унаследованный от него тип (правило 40).
• Все аксессоры свойств должны быть либо виртуальными, либо не виртуальными одновременно, то есть не допускается смешение виртуальных и не виртуальных аксессоров (правило 26).
• Упакованные значения не соответствуют CLS (правило 3). Например, следующий метод не соответствует CLS: void f (int^ boxedInt);. [см. примечание ниже]
• Неуправляемые указатели не соответствуют CLS (правило 17). Под это правило также подпадают и ссылки в C++. Доступ к нативным классам, структурам и объединениям также осуществляется по указателю [подробнее можно прочитать в главе 8 книги]. Из этого следует, что данные нативные типы также не соответствуют CLS.

  System::Int32 value = 1;
  System::Object ^boxedObject = value;    // упакованное значение value; соответствует object boxedObject = value; в C#
  System::Int32 ^boxedInt = value;        // также упакованное значение value, но в текущей версии C# аналогичный код написать невозможно
  

Создание обёрток для классов C++

Объявить управляемый класс с полем типа NativeLib: SampleCipher нельзя [подробнее можно прочитать в главе 8 книги]. Так как поля управляемых классов могут быть только указателями на нативные типы, следует использовать поле типа NativeLib: SampleCipher*. Экземпляр нативного класса должен быть создан в конструкторе обёртки и уничтожен в деструкторе.

namespace ManagedWrapper
{
    public ref class SampleCipher sealed
    {
        NativeLib::SampleCipher* pWrappedObject;

    public:
        SampleCipher(/* пока что аргументы можно опустить */)
        {
            pWrappedObject = new NativeLib::SampleCipher(/* пока что аргументы можно опустить */);
        }

        ~SampleCipher()
        {
            delete pWrappedObject;
        }

        /* ... */
    };
}

Отображение нативных типов на типы, соответствующие CLS

Если в нативную функцию передаётся ссылка C++ или указатель с семантикой передачи по ссылке, то в обёртке функции рекомендуется использовать отслеживаемую ссылку [см. примечание ниже]. Допустим, нативная функция имеет следующий вид:

void f(int& i);

Обёртка этой функции может выглядеть так:

void fWrapper(int% i)
{
    int j = i;
    f(j);
    i = j;
}

Как видно из этого примера, помимо затрат на переход между управляемым и нативным кодом, обёртки зачастую вынуждены тратить процессорное время на маршаллинг типов. Как будет показано позже, для более сложных типов эти затраты могут быть значительно выше.

Следует отметить, что некоторые другие языки .NET, включая C#, различают аргументы, передаваемые по ссылке, и аргументы, используемые только для возврата значения. Значение аргумента, передаваемого по ссылке, должно быть инициализировано перед вызовом. Вызываемый метод может изменить его значение, но он не обязан этого делать. Если аргумент используется только для возврата, то он передаётся неинициализированным и метод обязан изменить или проинициализировать его значение.

По умолчанию считается, что отслеживающая ссылка означает передачу по ссылке. Если вы хотите, чтобы аргумент использовался только для возврата значения, следует применить атрибут OutAttribute из пространства имён System: Runtime: InteropServices, как показано в следующем примере:

void fWrapper([Out] int% i);

void f(int& i1, const int& i2);

void fWrapper(int% i1, const int% i2);

namespace NativeLib
{
    class SampleCipher : public CryptoAlgorithm
    {
    public:
        SampleCipher(const unsigned char* pKey, int nKeySizeInBytes);
        /* ... на данный момент реализация не важна ... */
    };
}

namespace ManagedWrapper
{
    public ref class SampleCipher
    {
        NativeLib::SampleCipher* pWrappedObject;
    public:
        SampleCipher(array^ key);
        /* ... */
    };
}

Как реализовывать этот конструктор, зависит от реализации нативного класса SampleCipher. Если конструктор создаёт внутреннюю копию ключа, переданного в качестве аргумента pKey, то можно передать закрепляющий указатель на ключ:

SampleCipher::SampleCipher(array^ key)
{
    if (!key)
        throw gcnew ArgumentNullException("key");
    pin_ptr pp = &key[0];
    pWrappedObject = new NativeLib::SampleCipher(pp, key->Length);
}

namespace NativeLib
{
    class SampleCipher : public CryptoAlgorithm
    {
        const unsigned char* pKey;
        const int nKeySizeInBytes;
    public:
        SampleCipher(const unsigned char* pKey, int nKeySizeInBytes)
        : pKey(pKey), nKeySizeInBytes(nKeySizeInBytes)
        {}
        /* ... на данный момент остальные части класса не важны ... */
    };
}

Для этого надо внести изменения как в конструктор, так и в деструктор управляемой обёртки. Следующий код показывает возможную реализацию конструктора и деструктора:

public ref class SampleCipher
{
        unsigned char* pKey;
        NativeLib::SampleCipher* pWrappedObject;
    public:
        SampleCipher(array^ key)
        : pKey(0),
          pWrappedObject(0)
    {
        if (!key)
            throw gcnew ArgumentNullException("key");
        pKey = new unsigned char[key->Length];
        if (!pKey)
            throw gcnew OutOfMemoryException("Allocation on C++ free store failed");

        try
        {
            Marshal::Copy(key, 0, IntPtr(pKey), key->Length);

            pWrappedObject = new NativeLib::SampleCipher(pKey, key->Length);
            if (!pWrappedObject)
                throw gcnew OutOfMemoryException("Allocation on C++ free store failed");
        }
        catch (Object^)
        {
            delete[] pKey;
            throw;
        }
    }

    ~SampleCipher()
    {
        try
        {
            delete pWrappedObject;
        }
        finally
        {
            // удалить pKey, даже если деструктор pWrappedObject вызвал исключение
            delete[] pKey;
        }
    }

    /* остальная часть класса будет разобрана далее */
};

Этот код также показывает характерные накладные расходы управляемых обёрток. Помимо накладных расходов на вызов оборачиваемых нативных функций из управляемого кода, зачастую добавляются накладные расходы на отображение между нативными и управляемыми типами.

Отображение исключений C++ на управляемые исключения

Для того, чтобы отобразить исключения конструктора, можно использовать блок try на уровне функции, как показано в следующем примере. Это позволит перехватить исключения, выброшенные как при инициализации членов класса, так и в теле конструктора.

SampleCipher::SampleCipher(array^ key)
try
: pKey(0),
  pWrappedObject(0)
{
    ..// реализация не отличается от указанной ранее
}
catch(NativeLib::CipherException& ex)
{
    throw gcnew CipherException(gcnew String(ex.what()));
}

Отображение управляемых массивов на нативные типы

class CryptoAlgorithm
{
public:
    virtual void Encrypt( const unsigned char* pData, int nDataLength,
                          unsigned char* pBuffer, int nBufferLength,
                          int& nNumEncryptedBytes) = 0;
    virtual void Decrypt( const unsigned char* pData, int nDataLength,
                          unsigned char* pBuffer, int nBufferLength,
                          int& nNumEncryptedBytes) = 0;
};

Для отображения Encrypt и Decrypt можно добавить следующий метод в ManagedWrapper: SampleCipher:

namespace ManagedWrapper
{
public ref class SampleCipher sealed
{
    // ...
    void Encrypt( array^ data, array^ buffer, int% nNumOutBytes)
    {
        if (!data)
            throw gcnew ArgumentException("data");
        if (!buffer)
            throw gcnew ArgumentException("buffer");

        pin_ptr ppData = &data[0];
        pin_ptr ppBuffer = &buffer[0];
        int temp = nNumOutBytes;
        pWrappedObject->Encrypt(ppData, data->Length, ppBuffer, buffer->Length, temp);
        nNumOutBytes = temp;
    }
}

Отображение других непримитивных типов

class EncryptingSender
{
    CryptoAlgorithm& cryptoAlg;

public:
    EncryptingSender(CryptoAlgorithm& cryptoAlg)
    : cryptoAlg(cryptoAlg)
    {}

    void SendData(const unsigned char* pData, int nDataLength)
    {
        unsigned char* pEncryptedData = new unsigned char[nDataLength];
        int nEncryptedDataLength = 0;

        // вызов виртуального метода
        cryptoAlg.Encrypt(pData, nDataLength,
                          pEncryptedData, nDataLength, nEncryptedDataLength);

        SendEncryptedData(pEncryptedData, nEncryptedDataLength);
    }

private:
    void SendEncryptedData(const unsigned char* pEncryptedData, int nDataLength)
    { /* отправка данных не касается проблем, обсуждаемых здесь */ }
};

using namespace NativeLib;
unsigned char key[] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15};

SampleCipher sc(key, 16);
EncryptingSender sender(sc);
unsigned char pData[] = { '1', '2', '3' };
sender.SendData(pData, 3);

public ref class EncryptingSender
{
    NativeLib::SampleCipher* pSampleCipher;
    NativeLib::EncryptingSender* pEncryptingSender;

public:
    EncryptingSender(array^ key)
    try
    : pSampleCipher(0),
      pEncryptingSender(0)
    {
        if (!key)
            throw gcnew ArgumentNullException("key");

        pin_ptr ppKey = &key[0];
        pSampleCipher = new NativeLib::SampleCipher(ppKey, key->Length);
        if (!pSampleCipher)
            throw gcnew OutOfMemoryException("Allocation on C++ free store failed");
        try
        {
            pEncryptingSender = new NativeLib::EncryptingSender(*pSampleCipher);
            if (!pEncryptingSender)
                throw gcnew OutOfMemoryException("Allocation on C++ free store failed");
        }
        catch (Object^)
        {
            delete pSampleCipher;
            throw;
        }
    }
    catch(NativeLib::CipherException& ex)
    {
        throw gcnew CipherException(gcnew String(ex.what()));
    }

    // .. для простоты понимания надёжное освобождение ресурсов и другие методы опущены
};

public ref class SampleCipher sealed
{
    unsigned char* pKey;
    NativeLib::SampleCipher* pWrappedObject;

internal:
    [CLSCompliant(false)]
    NativeLib::SampleCipher& GetWrappedObject()
    {
        return *pWrappedObject;
    }

    ... в остальном SampleCipher идентичен предыдущим примерам ...
};

public ref class EncryptingSender
{
    NativeLib::EncryptingSender* pEncryptingSender;

public:
    EncryptingSender(SampleCipher^ cipher)
    {
        if (!cipher)
            throw gcnew ArgumentException("cipher");

        pEncryptingSender =
            new NativeLib::EncryptingSender(cipher->GetWrappedObject());
        if (!pEncryptingSender)
            throw gcnew OutOfMemoryException("Allocation on C++ free store failed");
    }

    // ... в остальном код EncryptingSender идентичен предыдущим примерам ...
};

public interface class INativeCryptoAlgorithm
{
    [CLSCompliant(false)]
    NativeLib::CryptoAlgorithm& GetWrappedObject();
};

public ref class SampleCipher sealed : INativeCryptoAlgorithm
{
    // ...

internal:
    [CLSCompliant(false)]
    virtual NativeLib::CryptoAlgorithm& GetWrappedObject()
        = INativeCryptoAlgorithm::GetWrappedObject
    {
        return *pWrappedObject;
    }
};

EncryptingSender::EncryptingSender(INativeCryptoAlgorithm^ cipher)
{
    if (!cipher)
        throw gcnew ArgumentException("cipher");

    pEncryptingSender =
        new NativeLib::EncryptingSender(cipher->GetWrappedObject());
    if (!pEncryptingSender)
        throw gcnew OutOfMemoryException("Allocation on C++ free store failed");
}

public ref class CryptoAlgorithm abstract
{
public protected:
    virtual void Encrypt( array^ data,
                          array^ buffer, int% nNumOutBytes) abstract;
    virtual void Decrypt( array^ data,
                          array^ buffer, int% nNumOutBytes) abstract;

    // оставшаяся часть этого класса будет рассмотрена позднее
};

class CryptoAlgorithmProxy : public NativeLib::CryptoAlgorithm
{
public:
    virtual void Encrypt( const unsigned char* pData, int nNumInBytes,
                          unsigned char* pBuffer, int nBufferLen,
                          int& nNumOutBytes);
    virtual void Decrypt( const unsigned char* pData, int nNumInBytes,
                          unsigned char* pBuffer, int nBufferLen,
                          int& nNumOutBytes);

    // оставшаяся часть этого класса будет рассмотрена позднее
};

class CryptoAlgorithmProxy : public NativeLib::CryptoAlgorithm
{
    gcroot target;

public:
    CryptoAlgorithmProxy(CryptoAlgorithm^ target)
    : target(target)
    {}

    // Encrypt и Decrypt будут рассмотрены позднее
};

public ref class CryptoAlgorithm abstract
: INativeCryptoAlgorithm
{
    CryptoAlgorithmProxy* pWrappedObject;
public:
    CryptoAlgorithm()
    {
        pWrappedObject = new CryptoAlgorithmProxy(this);
        if (!pWrappedObject)
            throw gcnew OutOfMemoryException("Allocation on C++ free store failed");
    }
    ~CryptoAlgorithm()
    {
        delete pWrappedObject;
    }
internal:
    [CLSCompliant(false)]
    virtual NativeLib::CryptoAlgorithm& GetWrappedObject()
        = INativeCryptoAlgorithm::GetWrappedObject
    {
        return *pWrappedObject;
    }

public protected:
    virtual void Encrypt( array^ data,
                          array^ buffer, int% nNumEncryptedBytes) abstract;
    virtual void Decrypt( array^ data,
                          array^ buffer, int% nNumEncryptedBytes) abstract;
};

void CryptoAlgorithmProxy::Encrypt( const unsigned char* pData, int nDataLength,
                        unsigned char* pBuffer, int nBufferLength,
                        int& nNumOutBytes)
{
    array^ data = gcnew array(nDataLength);
    Marshal::Copy(IntPtr(const_cast(pData)), data, 0, nDataLength);
    array^ buffer = gcnew array(nBufferLength);
    target->Encrypt(data, buffer, nNumOutBytes);
    Marshal::Copy(buffer, 0, IntPtr(pBuffer), nBufferLength);
}