Universal Windows Platform: Plugins on IL2CPP Scripting Backend

The plugin model for Universal Windows Platform is similar to other Unity platforms (such as Windows standalone).

Managed plugins

By default, IL2CPP targets .NET 2.0 API compatiblity level. That means it does not support managed plugins targeting .NET 4.5 or consuming any of Windows Runtime APIs. All managed plugins must be targeting .NET 4.5 or equivalent API when using this compatiblity level. You can switch to .NET 4.6 API compatibilty level in Player settings if you wish to lift these restrictions.

Note The .Net 3.5 scripting runtime is deprecated, but it will be available for Unity 2018.3 and 2018.4 LTS. Please migrate or start new Projects with the .NET 4.x runtime.

IL2CPP scripting backend exposes the exact same .NET API surface as Unity editor or standalone player, so it’s possible to use the same plugins without the need to compile separate versions targetting different .NET API for Universal Windows Platform.

Plugins Nativos

El IL2CPP scripting backend soporta el uso de plugins nativos a través del mecanismo de P/Invoke . Esto significa que puede llamar a los plugins nativos directamente desde su código C# especificando el prototipo de función nativa y luego llamarla. Por ejemplo:

[DllImport("MyPlugin.dll")]
private static extern int CountLettersInString([MarshalAs(UnmanagedType.LPWSTR)]string str);

private void Start()
{
    Debug.Log(CountLettersInString("Hello, native plugin!"));
}

La implementación de tal función dentro del MyPlugin.dll se vería así:

extern "C" __declspec(dllexport)
int __stdcall CountLettersInString(wchar_t* str)
{
    int length = 0;
    while (*str++ != nullptr)
        length++;
    return length;
}

Las reglas de ordenación P/Invoke coinciden aquellas del ordenamiento .NET oficial, con excepciones de unos pocos tipos no soportados:

• AnsiBStr
• Currency
• SAFEARRAY
• IDispatch
• TBStr
• VBByRefStr

The default calling convention for P/Invoke functions on x86 is __stdcall.

Los Native Plugins pueden ser autorizados en dos maneras: DLL precompiladas o código fuente C++.

Native plugins Pre-compilados

P/Invoking a unos plugins nativos precompilados funciona al cargar el DLL en tiempo de ejecución, encontrando el punto de entrada de la función y luego llamarla. Estos DLLs deben estar compilados contra el Windows SDK apropiado para la arquitectura CPU objetiva. Los DLLs también deben estar configurados en el Plugin Inspector cuando se agregue al proyecto de Unity.

Plugins nativos de código fuente C++

It is possible to add C++ (.cpp) code files directly into Unity project, which will act as a plugin in Plugin Inspector. If configured to be compatible with Universal Windows Platform and IL2CPP scriping backend, these C++ files will be compiled together with C++ code that gets generated from managed assemblies:

Ya que las funciones están enlazadas juntas con código generado C++, no hay un DLL separada para P/Invoke. Debido a esto, es posible utilizar la palabra clave “__Internal” en lugar del nombre del DLL, que haría que la responsabilidad del C++ Linker resuelva las funciones, en vez de cargarlas en tiempo de ejecución:

[DllImport("__Internal")]
private static extern int CountLettersInString([MarshalAs(UnmanagedType.LPWSTR)]string str);

Ya que la llamada está resolvida por el linker (enlazador), crear un error en la declaración de la función en el lado managed producirá un error de linker (enlazamiento), en vez de un error en tiempo de ejecución. Esto también significa que no hay necesidad de que una carga dinámica tome lugar en tiempo de ejecución, y la función se llama directamente. Esto decrece significativamente la sobre carga de una llamada P/Invoke.

Limitaciones de P/Invoke

On Universal Windows Platform you cannot P/Invoke into specific system libraries by specifying the dll name (like “kernelbase.dll”) when using IL2CPP scripting backend. Attempting to P/Invoke into any DLL that exists outside of the project will result in DllNotFoundException at runtime.

No obstante, es posible P/Invoke a estas funciones del sistema, especificando la palabra clave “Internal”" en vez del nombre del DLL, que resulta en un linker (enlazador) que resuelve las funciones en el tiempo de construcción.

Mirar también

Plugin Inspector

• • 2018–08–03 Page amended with no editorial review
  
• .NET 3.5 scripting runtime deprecated in 2018.3