# Extensiones .NET Una extensión es una DLL de .NET que un programa DKL carga con `_import_library` y cuyas funciones expone con `_map_function`. Así funcionan las bibliotecas del motor (`functions.dkh`, `dbr.dkh`…), las de terceros (`csv.dkh`, `image.dkh`…) y las DLL propias de sus aplicaciones. Esta página explica dónde van las DLL, cómo se cargan, qué extensiones de 1.x funcionan en 2.0 y por qué hay que reiniciar al reemplazarlas. ## Dónde van las DLL **Junto a `dkl`**, en la carpeta de la instalación (`/opt/devkron`, `/usr/devkron`, `C:\devkron`). `_import_library("X.dll")` sin ruta busca ahí, como en 1.x. Una DLL que dependa de otras (por ejemplo, de una biblioteca de terceros como `CsvHelper.dll`) necesita sus dependencias en la misma carpeta. ```dkl #include "dkli.dkh" #! program "extension" { #include "functions.dkh" ref lib = _import_library("System.Web.HttpUtility.dll") do _map_function(lib, "System.Web.HttpUtility", "UrlEncode", "web.urlencode", "System.String", "$") do print(web.urlencode("Lápiz y goma & más")) } ``` ```text L%c3%a1piz+y+goma+%26+m%c3%a1s ``` `_import_library` también acepta una ruta absoluta, pero no la use: dificulta mover la instalación y abre la puerta a cargar DLL de carpetas que otros pueden escribir. Si la DLL no existe, el error dice dónde la buscó: ```text {1} Could not load file or assembly '/opt/devkron/MiEmpresa.Utilerias.dll'. The system cannot find the file specified. [noext.dkl][Ln= 6] ``` La sintaxis completa de `_import_library`, `_map_function`, `_new`, `_invoke`, `_get` y `_set` está en la [Referencia del lenguaje](/es/devkron/2.0/lenguaje/). ## Reemplazar una DLL requiere reiniciar El runtime carga cada DLL **una sola vez por proceso** y no la libera. Por eso, al copiar una DLL nueva o actualizada: - el **servidor FastCGI** debe **reiniciarse** (`sudo systemctl restart devkron`, o detener y arrancar la tarea en Windows) para usarla; mientras tanto sigue con la versión que ya cargó; - los programas de **consola** la toman en su siguiente ejecución, porque cada ejecución es un proceso nuevo. Es igual que en 1.x. Los cambios a `.dkl`, `.dk` y `.dkh` no requieren reinicio. En Windows, el archivo de una DLL cargada queda bloqueado: detenga el servidor antes de reemplazarla. ## Extensiones de 1.x en 2.0 Las DLL de extensiones que funcionaban con Devkron 1.x **funcionan sin recompilar** en 2.0. Se probaron extensiones reales de distintos tipos, por HTTP y por consola, comparando contra el motor 1.x: | Tipo de extensión | Resultado en 2.0 | |---|---| | extensión con componentes nativos de terceros (procesamiento de imágenes con ImageMagick, nativo Linux x64) | igual: imágenes idénticas | | extensión que depende de una biblioteca de terceros (lectura de CSV con `CsvHelper.dll`) | igual: 219 archivos CSV (14 700 filas) dan el mismo JSON | | biblioteca de terceros usada directamente (`Markdig.dll`, conversión de Markdown) | HTML idéntico | | extensión compilada para el .NET Framework 4.5 de Windows | carga y da lo mismo | | extensiones propias que solo exponen funciones para `_map_function` | igual | | DLL del sistema que se copiaban junto a `dkl` (`System.Net`, `System.Web.HttpUtility`, `System.IO.Compression.ZipFile`, `System.Text.RegularExpressions`, `System.Text.Encoding.CodePages`) | **vienen en la distribución 2.0**: ya no hay que copiarlas | Reglas: - Al migrar, copie de la instalación 1.x **solo las DLL de extensiones** y nunca sobrescriba un archivo de la distribución 2.0 (`Devkron*.dll`, `System.*.dll`, `Microsoft.*.dll`, drivers). Para ver cuáles son extensiones: ```bash comm -23 <(cd /opt/devkron && ls *.dll | sort) <(cd /opt/devkron2 && ls *.dll | sort) ``` - Una extensión que use la **API interna del motor** y acceda a `ContextBlock.Variables` o `ContextBlock.GlobalVars` necesita **recompilarse** contra 2.0: dejaron de ser `Dictionary` y ahora son `VariableTable`, con los mismos métodos (`TryGetValue`, `ContainsKey`, indexador, `Add`, `Remove`, `Keys`, `Values`, `foreach`) y `ToDictionary()` si necesita una copia. `GetVariable`/`SetVariable` no cambiaron. Las extensiones que solo exponen funciones para `_map_function` no se ven afectadas. - Dentro de cada ejecución la cultura del hilo es la **invariante**: una función de la extensión que formatee con `ToString()` sin `IFormatProvider` obtiene texto con punto decimal y nombres en inglés. Vea [Cultura](/es/devkron/2.0/migracion/cultura.md). - **ImageMagick ya no está dentro del motor**: para imágenes use la biblioteca de terceros [image.dkh](/es/devkron/2.0/bibliotecas/terceros/image.md), o la extensión de imágenes que ya usaba con 1.x, que funciona sin recompilar. ## Escribir una extensión nueva para 2.0 - Compílela para el framework de destino `net10.0` o para .NET Standard 2.0. - Exponga **métodos estáticos públicos** con tipos simples (`string`, `decimal`, `bool`, `int`, `byte[]`, `IDictionary`, `List`): los registros de DKL llegan como diccionarios y las listas como `List`. - Use siempre `CultureInfo.InvariantCulture` al convertir números y fechas a texto y de texto. - Entregue un `.dkh` que haga el `_import_library` y los `_map_function`, para que los programas solo hagan `#include`. ## Errores típicos | Síntoma | Causa | Solución | |---|---|---| | `Could not load file or assembly '…/X.dll'` | la DLL no está junto a `dkl` | cópiela ahí | | `Could not load file or assembly 'Y, Version=…'` al llamar una función | falta una **dependencia** de la extensión | copie también sus dependencias junto a `dkl` | | la versión nueva de la DLL no se nota | el servidor FastCGI tiene cargada la anterior | reinícielo | | `Función: x no reconocida o no registrada` | falta el `#include` del `.dkh` que mapea la función, o el nombre de `_map_function` no coincide | revise el encabezado | | `Input string was not in a correct format` al mapear | se escribió el nombre de un tipo (`System.String`) en el tipo de retorno | use los códigos `$`, `#`, `*` o `void` | | una extensión con API interna falla con `MissingMethodException` sobre `Variables` | usa `ContextBlock.Variables` como `Dictionary` | recompílela contra 2.0 |