Mejores prácticas

Mejores prácticas para actividades de base de datos, que cubren cadenas de conexión para SQL Server, Oracle, MySQL y otras bases de datos, procedimientos almacenados y solución de problemas.

Utilizar un procedimiento almacenado con OracleRefCursor

Al utilizar procedimientos almacenados en Oracle, asegúrate de que el CURSOR REF esté vinculado correctamente con la variable Oracle.ManagedDataAccess.Types.OracleRefCursor.

Para ello, debes asegurarte de que el número de parámetros y su tipo coincidan con la configuración de los en la propiedad Parámetros de la actividad Ejecutar consulta.

Puedes obtener el contenido del cursor utilizando la actividad Invocar código o puedes pasarlo a otra consulta de la base de datos como parámetro de entrada. Aquí hay un código de invocación de muestra para convertirlo en una tabla de datos:

Oracle.ManagedDataAccess.Client.OracleDataReader reader2 = myRefCursor.GetDataReader();
                dt = new DataTable();
                dt.Load(reader2);

Debes desechar el cursor cuando hayas terminado con él. Puedes hacerlo con la actividad Invocar código (myRefCursor.Dispose), con la actividad Invocar método del paquete de actividades del sistema o a través de un comando SQL que ejecutas.

Ejecutar procedimientos almacenados con parámetros

Las actividades Ejecutar consulta y Ejecutar comando pueden llamar a un procedimiento almacenado en lugar de una instrucción SQL simple. Usa Ejecutar consulta cuando el procedimiento devuelva un conjunto de resultados y Ejecutar comando cuando no lo haga.

Para llamar a un procedimiento almacenado:

1. Establece la propiedad Tipo de comando en Procedimiento almacenado.
2. Introduce el nombre del procedimiento en el campo SQL , sin un contenedor EXEC o CALL .
3. Añade una entrada a la colección Parámetros para cada parámetro del procedimiento.

Cada entrada de Parámetros tiene los siguientes atributos:

• Un nombre.
• Una dirección (In, Out o In/Out).
• Un tipo.
• Un valor.

Los valores Out y In/Out se leen después de la llamada. La forma en que se interpretan los nombres y el orden de los parámetros depende del proveedor de la base de datos, por lo que la orientación difiere según la base de datos en las siguientes secciones.

Base de datos	Proveedor	Cómo llamar	Vinculación de parámetros
Microsoft SQL Server	Microsoft.Data.SqlClient	Tipo de comando = Procedimiento almacenado, SQL = nombre del procedimiento	Por nombre (@name); el orden no importa
Oracle	Oracle.ManagedDataAccess.Client	Tipo de comando = Procedimiento almacenado, SQL = nombre del procedimiento	Por posición; añadir parámetros en el orden declarado del procedimiento
MySQL/MariaDB	Conectividad abierta de base de datos (ODBC)	Tipo de comando = Texto, SQL = CALL procedure_name(?, ?)	Marcadores de posición ?
PostgreSQL	ODBC	Tipo de comando = Texto, SELECT * FROM function_name(?) o CALL procedure_name(?)	Marcadores de posición ?
SQLite	Microsoft.Data.Sqlite	NoAplicable	SQLite no tiene procedimientos almacenados

Microsoft SQL Server

SQL Server vincula los parámetros por nombre, por lo que los nombres de las entradas de los Parámetros deben coincidir con los parámetros con prefijo @del procedimiento, y su orden no importa. Los parámetros de salida se devuelven cuando estableces la dirección de entrada en Out.

CREATE PROCEDURE dbo.usp_CountCustomers @Country NVARCHAR(5), @Total INT OUTPUT AS
BEGIN
    SET NOCOUNT ON;
    SELECT @Total = COUNT(*) FROM dbo.customer WHERE country = @Country;
END;

Configura Ejecutar comando con Tipo de comando = Procedimiento almacenado y SQL = dbo.usp_CountCustomers, a continuación, añade los parámetros:

Nombre	Dirección	Tipo	Valor
@Country	En	String	US
@Total	Salida	Int32	—

Después de la ejecución, @Total retiene el recuento. Para un procedimiento que devuelve filas, utiliza Ejecutar consulta en su lugar; el resultado está disponible en la salida de la tabla de datos .

Oracle

Oracle vincula los parámetros por posición, no por nombre, por lo que debes añadir las entradas de Parámetros en el mismo orden en que las declara el procedimiento. Un procedimiento devuelve un conjunto de resultados a través de un parámetro OUT SYS_REFCURSOR ; declara esa entrada con el tipo OracleRefCursor y la dirección Out , y las filas se devuelven en la salida de la tabla Datos de Ejecutar consulta. Consulta también Utilizar un procedimiento almacenado con OracleRefCursor.

CREATE OR REPLACE PROCEDURE get_customers(p_country IN VARCHAR2, p_cursor OUT SYS_REFCURSOR) AS
BEGIN
    OPEN p_cursor FOR SELECT id, name FROM customer WHERE country = p_country ORDER BY id;
END;

Configura Ejecutar consulta con Tipo de comando = Procedimiento almacenado y SQL = get_customers, a continuación, añade los parámetros en el orden de declaración:

Nombre	Dirección	Tipo	Valor
p_country	En	String	US
p_cursor	Salida	OracleRefCursor	—

ADVERTENCIA:

Oracle vincula los parámetros por posición. Si las entradas de Parámetros no están en el orden declarado del procedimiento, se asignan valores a los parámetros incorrectos y la llamada falla o devuelve una salida vacía.

MySQL y MariaDB

Cuando te conectes a MySQL o MariaDB a través de ODBC, llama al procedimiento con el tipo de comando Texto y una declaración CALL que utiliza marcadores de posición posicionales ? . Un SELECT dentro del procedimiento se devuelve en la salida de la tabla de datos de Ejecutar consulta.

CREATE PROCEDURE list_customers(IN p_country VARCHAR(5))
BEGIN
    SELECT id, name FROM customer WHERE country = p_country ORDER BY id;
END

Configura Ejecutar consulta con Tipo de comando = Texto y Consulta SQL = CALL list_customers(?), a continuación, añade un parámetro In para el marcador de posición.

Nota:

Para los procedimientos MySQL con parámetros OUT , lee el valor de un conjunto de resultados devuelto o utiliza el patrón CALL procedure_name(?, @out); SELECT @out; , porque los valores OUT no siempre se asignan a la entrada del parámetro a través de ODBC.

PostgreSQL

PostgreSQL expone dos tipos de rutinas: funciones, llamadas con SELECT, y procedimientos, llamados con CALL. Cuando te conectes a través de ODBC, utiliza el tipo de comando Texto con marcadores de posición posicionales ? . Usa Ejecutar consulta para una función que devuelva filas.

CREATE FUNCTION get_customers_by_country(p_country text)
RETURNS TABLE(id int, name text) LANGUAGE sql AS $$
    SELECT id, name FROM customer WHERE country = p_country ORDER BY id;
$$;

Configura Ejecutar consulta con Tipo de comando = Texto y Consulta SQL = SELECT * FROM get_customers_by_country(?), a continuación, añade un parámetro In . Para invocar un procedimiento creado con CREATE PROCEDURE, utiliza CALL procedure_name(?) en su lugar.

SQLite

SQLite no admite procedimientos almacenados. Mantén la lógica en tu flujo de trabajo utilizando declaraciones parametrizadas de Ejecutar consulta y Ejecutar comando , o define una vista reutilizable.

Cadenas de conexión para diferentes sistemas de bases de datos

Esta guía proporciona cadenas de conexión de muestra para la actividad Conectar a la base de datos , lo que te permite conectarte a varias bases de datos utilizando controladores nativos y ODBC. Incluye ejemplos de cadenas de conexión para:

• Microsoft SQL Server (incluida la autenticación de Microsoft Entra ID)
• Oracle
• PostgreSQL
• MySQL
• AmazonAurora
• Microsoft Access
• SAP HANA
• IBM Db2
• SQLite

Una sección de solución de problemas para errores de conexión comunes sigue a los ejemplos. Sigue las mejores prácticas para garantizar una conectividad de base de datos segura y eficiente.

Microsoft SQL Server

Formatos de cadena de conexión comunes para Microsoft SQL Server cuando se utiliza Microsoft.Data.SqlClient.

Autenticación de SQL Server y ODBC

1. Uso de la autenticación de SQL Server:

   Data Source=SERVER_NAME;Initial Catalog=DATABASE_NAME;User ID=USERNAME;Password=<your-password>;

2. Con un puerto específico:

   Data Source=SERVER_NAME,PORT_NUMBER;Initial Catalog=DATABASE_NAME;User ID=USERNAME;Password=<your-password>;

3. Utilizando el controlador ODBC:

   Driver={ODBC Driver 18 for SQL Server};Server=SERVER_NAME;Database=DATABASE_NAME;Uid=USERNAME;Pwd=<your-password>;Encrypt=yes;TrustServerCertificate=no;

Importante:

De forma predeterminada, estas actividades se conectan con Encrypt=True. Una conexión a un servidor con un certificado autofirmado o que no sea de confianza falla a menos que añadas TrustServerCertificate=True (solo prueba o desarrollo) o instales un certificado de confianza. Para un comportamiento predecible, establece ambas palabras clave explícitamente, por ejemplo Encrypt=True;TrustServerCertificate=False;.

Autenticación de Microsoft Entra ID

1. Utilizar la autenticación de contraseña (obsoleta por Microsoft e incompatible con la autenticación multifactor (MFA); prefiere la identidad interactiva, principal de servicio o administrada):

   Server=tcp:SERVER.database.windows.net,1433;Initial Catalog=DATABASE_NAME;Authentication=Active Directory Password;User ID=[e-mail];Password=<your-password>;Encrypt=True;

2. Uso de la autenticación principal de servicio (para robots desatendidos):

   Server=tcp:SERVER.database.windows.net,1433;Initial Catalog=DATABASE_NAME;Authentication=Active Directory Service Principal;User ID=APP_CLIENT_ID;Password=<your-client-secret>;Encrypt=True;

3. Uso de la autenticación de identidad gestionada (omite User ID para una identidad asignada por el sistema; para una identidad asignada por el usuario, establécela en el ID de cliente de la identidad):

   Server=tcp:SERVER.database.windows.net,1433;Initial Catalog=DATABASE_NAME;Authentication=Active Directory Managed Identity;User ID=USER_ASSIGNED_MI_CLIENT_ID;Encrypt=True;

4. Uso de la autenticación integrada (utiliza la autenticación de Windows integrada con una identidad de Active Directory local federada):

   Server=tcp:SERVER.database.windows.net,1433;Initial Catalog=DATABASE_NAME;Authentication=Active Directory Integrated;Encrypt=True;

5. Utilizar autenticación interactiva (abre un navegador con una solicitud de MFA; solo para uso attended o de desarrollo, no para robots desatendidos):

   Server=tcp:SERVER.database.windows.net,1433;Initial Catalog=DATABASE_NAME;Authentication=Active Directory Interactive;User ID=[e-mail];Encrypt=True;

Para el controlador ODBC, los valores de palabra clave equivalentes no tienen espacios: ActiveDirectoryPassword, ActiveDirectoryServicePrincipal, ActiveDirectoryMsi (identidad administrada), ActiveDirectoryIntegrated y ActiveDirectoryInteractive. ActiveDirectoryInteractive está disponible solo en Windows.

Consejo:

Si el mismo flujo de trabajo se ejecuta tanto en un robot como en una máquina de desarrollo, utiliza Authentication=Active Directory Default. Utiliza DefaultAzureCredential, que prueba variables de entorno, identidad de carga de trabajo e identidad administrada antes de recurrir a las credenciales de herramienta de desarrollador.

Puedes obtener más información sobre la sintaxis de la cadena de conexión en la documentación oficial de Microsoft y sobre la autenticación de Microsoft Entra en la documentación de autenticación de Microsoft Entra.

Archivo de Excel

Driver={Microsoft Excel Driver (*.xls, *.xlsx, *.xlsm, *.xlsb)};DBQ=C:\full\path\to\the\sampleFile.xlsx;

Acceso a datos gestionados por Oracle

Data Source=(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=XEPDB1)));User Id=system;Password=<your-password>;

También puedes utilizar la forma abreviada de Conexión fácil: Data Source=//HOST_NAME:1521/SERVICE_NAME;User Id=USERNAME;Password=<your-password>;.

Para obtener más información, consulta la documentación del proveedor de datos de Oracle para.NET.

Controlador MySQL ODBC 8.3 Unicode

Driver={MySQL ODBC 8.3 Unicode Driver};Server=SERVER_NAME;Database=DATABASE_NAME;User=USERNAME;Password=<your-password>;Option=3;

Puedes obtener más información al respecto a través de la página de documentación oficial de MySQL aquí.

Controlador ANSI ODBC 8.3 de MySQL

Driver={MySQL ODBC 8.3 ANSI Driver};Server=SERVER_NAME;Database=DATABASE_NAME;User=USERNAME;Password=<your-password>;Option=3;

Reemplaza la versión en el nombre del controlador con la versión de MySQL Connector/ODBC instalada en la máquina (por ejemplo, MySQL ODBC 9.4 Unicode Driver); el nombre debe coincidir exactamente con el controlador registrado. Da preferencia al controlador Unicode sobre el controlador ANSI para evitar corromper los datos que no son ASCII. El marcador heredado Option=3 es opcional y no es necesario para el uso típico.

PostgreSQL

Driver={PostgreSQL Unicode};Server=SERVER_NAME;Port=5432;Database=DATABASE_NAME;Uid=USERNAME;Pwd=<your-password>;

Usa la variante ANSI Driver={PostgreSQL ANSI};… solo para codificaciones heredadas de un solo byte; prefiere el controlador Unicode para las bases de datos UTF-8. Añade sslmode=require; (en minúsculas) para aplicar TLS.

Importante:

El nombre Driver={...} debe coincidir con el controlador registrado en la máquina que ejecuta el robot. Dependiendo del instalador, el controlador psqlODBC de 64 bits se registra como PostgreSQL Unicode o PostgreSQL Unicode(x64) (y los equivalentes ANSI). Si el nombre no coincide con un controlador registrado, la conexión falla con "nombre de origen de datos no encontrado".

Verifica el nombre registrado exacto en el Administrador de origen de datos ODBC de 64 bits (C:\Windows\System32\odbcad32.exe).

Puedes obtener más información a través de la documentación de psqlODBC.

Amazon Aurora (compatible con MySQL)

La edición compatible con MySQL de Amazon Aurora utiliza el protocolo de conexión MySQL, por lo que te conectas con el controlador MySQL Connector/ODBC. Punto Server en el punto final del clúster de Aurora (escritor):

Driver={MySQL ODBC 9.4 Unicode Driver};Server=CLUSTER.cluster-xxxx.REGION.rds.amazonaws.com;Port=3306;Database=DATABASE_NAME;User=USERNAME;Password=<your-password>;

Base de datos autónoma de Oracle (ATP/ADW) con monedero

Para conectarse a la base de datos autónoma de Oracle (Procesamiento de transacciones autónomo o Almacén de datos autónomo):

1. Descarga la cartera de instancia (Wallet_DBNAME.zip) desde Oracle Cloud Infraestructura.
2. Extrae todos los archivos del archivo de la cartera en una carpeta de la máquina del robot.
3. Establece la variable de entorno TNS_ADMIN en esa carpeta.
4. Edita el directorio WALLET_LOCATION en el sqlnet.ora de la cartera a esa misma carpeta. La cartera se envía con un marcador de posición ?/network/admin que debes reemplazar, porque TNS_ADMIN por sí solo no es suficiente.

Con la cartera de inicio de sesión automático (cwallet.sso), no se necesita la contraseña de la cartera. De lo contrario, proporciona la contraseña de la cartera para que el controlador pueda abrir el ewallet.p12 protegido por contraseña.

A continuación, utiliza un alias de servicio de tnsnames.ora (DBNAME_high, DBNAME_medium o DBNAME_low, más DBNAME_tp y DBNAME_tpurgent en bases de datos de procesamiento de transacciones):

Data Source=DBNAME_low;User Id=USERNAME;Password=<your-password>;

Consejo:

También puedes conectarte sin monedero utilizando TLS unidireccional, siempre que la instancia de la base de datos autónoma esté configurada para permitir conexiones TLS. Las instancias configuradas para TLS mutuo (mTLS) solo requieren la cartera.

Puedes obtener más información a través de la documentación de configuración de Oracle ODP.NET.

Microsoft Access

Utilizando el controlador ODBC:

Driver={Microsoft Access Driver (*.mdb, *.accdb)};Dbq=C:\full\path\to\database.accdb;Uid=Admin;Pwd=;

Utilizando el proveedor OLE DB (System.Data.OleDb, disponible solo en Windows):

Provider=Microsoft.ACE.OLEDB.12.0;Data Source=C:\full\path\to\database.accdb;Persist Security Info=False;

Para un archivo protegido por contraseña, anexa Jet OLEDB:Database Password=<your-password>; a la cadena OLE DB.

Importante:

Tanto el controlador ODBC como el proveedor ACE OLE DB provienen del redistribuible del motor de base de datos de Microsoft Access, cuya arquitectura (x86 o x64) debe coincidir con la arquitectura del robot y del proyecto. Una falta de coincidencia da como resultado un mensaje "el proveedor no está registrado en la máquina local" error.

SAP HANA

Driver={HDBODBC};ServerNode=HOST_NAME:3NN15;UID=USERNAME;PWD=<your-password>;

Usa HDBODBC para robots de 64 bits (HDBODBC32 solo para un proceso de 32 bits). Para una base de datos de un solo contenedor o el primer tenant, el puerto es 3NN15, donde NN es el número de instancia de dos dígitos, por ejemplo, 30015 para la instancia 00, o 30515 para la instancia 05.

Para un sistema de contenedor de base de datos multitenant (MDC), conéctate a través del puerto de base de datos del sistema 3NN13 y nombra el tenant, que es la forma que SAP recomienda:

Driver={HDBODBC};ServerNode=HOST_NAME:30013;DATABASENAME=TENANT_DB;UID=USERNAME;PWD=<your-password>;

Importante:

Para SAP HANA Cloud (a diferencia de SAP HANA local), el host es un punto final de estilo UUID en el puerto 443 y la conexión siempre está cifrada. Establece encrypt=TRUE explícitamente para el cliente SAP HANA 2.5 y anteriores; los clientes más nuevos lo infieren en el puerto 443. El esquema de puertos 3NN15 se aplica solo a los sistemas locales.

IBM Db2

Driver={IBM DB2 ODBC DRIVER};Database=DATABASE_NAME;Hostname=HOST_NAME;Port=50000;Protocol=TCPIP;Uid=USERNAME;Pwd=<your-password>;

El nombre del controlador registrado puede ser específico de la instalación: con varias copias de Db2, podría ser IBM DB2 ODBC DRIVER - DB2COPY1. Verifica el nombre exacto en el Administrador de origen de datos ODBC en Windows, o en odbcinst.ini en Linux. El puerto 50000 es el valor predeterminado común, pero el puerto real lo establece SVCENAME para cada instancia.

SQLite

Las actividades de la base de datos utilizan Microsoft.Data.Sqlite. Proporciona la ruta al archivo de la base de datos:

Data Source=C:\full\path\to\database.db;

Las palabras clave opcionales incluyen Mode=ReadOnly (o ReadWrite / ReadWriteCreate), Foreign Keys=True para aplicar la integridad referencial y Cache=Shared. La palabra clave Version=3 no es válida aquí: pertenece al proveedor System.Data.SQLite más antiguo y da como resultado un error.

Puedes obtener más información a través de la documentación de Microsoft.Data.Sqlite.

JDBC

Las actividades de la base de datos se ejecutan en.NET y no utilizan controladores JDBC directamente. Para llegar a una base de datos a la que normalmente accederías a través de JDBC, utiliza su controlador ODBC con la cadena de conexión ODBC para esa base de datos en esta guía, o implementa la conexión en un flujo de trabajo codificado utilizando el controlador.NET o ADO.NET del proveedor de la base de datos.

Solución de problemas de conexión comunes

No se ha encontrado el nombre del origen de datos (error IM002)

ERROR [IM002] [Microsoft][ODBC Driver Manager] Data source name not found, and no default driver specified

El controlador ODBC nombrado en Driver={...} no está instalado o está registrado con un nombre o arquitectura diferente. Para solucionarlo:

1. Instala el controlador ODBC correspondiente.
2. Confirma que el controlador aparece en el Administrador de origen de datos ODBC que coincide con la arquitectura del robot. Hay administradores independientes de 32 bits y de 64 bits.
3. Copia el nombre del controlador exacto del administrador en Driver={...}. El nombre suele ser específico de la versión o instalación (por ejemplo, PostgreSQL Unicode(x64), MySQL ODBC 9.4 Unicode Driver o IBM DB2 ODBC DRIVER - DB2COPY1).

No se pudo cargar el controlador (error IM003)

ERROR [IM003] Specified driver could not be loaded due to system error 1114

El error del sistema 1114 significa que se encontró la biblioteca de controladores, pero su rutina de inicialización falló; normalmente, falta una dependencia (como un tiempo de ejecución requerido) o una falta de coincidencia de la arquitectura o la versión. Es común con Oracle Instant Client (SQORA32.dll) e IBM Db2 (DB2CLIO.DLL). Para solucionarlo:

1. Asegúrate de que la arquitectura del controlador coincida con el tiempo de ejecución.
2. Instala cualquier requisito previo que requiera el controlador.
3. Vuelva a instalar o actualice el controlador.

Arquitectura de controladores y soporte de plataforma

Instala el controlador de la base de datos que coincida con la arquitectura de runtime del proyecto. Los proyectos de Windows se ejecutan como procesos de 64 bits y necesitan el controlador ODBC u OLE DB de 64 bits. Los proyectos de Windows: heredado se ejecutan como procesos de 32 bits y necesitan el controlador de 32 bits.

OLE DB (System.Data.OleDb, utilizado para Access y Excel) solo está disponible en Windows. ODBC funciona en Windows y en robots Linux o macOS cuando unixODBC 2.3.1 o posterior y el controlador de destino están instalados en esa máquina.

Consejo:

Después de instalar un controlador, reinicia Studio o el robot para que detecte el controlador.