🪄 Introducción

Cuando desarrollamos aplicaciones en Power Apps, una de las necesidades más comunes es crear o actualizar registros en nuestras fuentes de datos, ya sea en Dataverse, SharePoint, Excel, o una Colección local.

La función Patch() es una de las más poderosas y versátiles de Power Apps, ya que permite realizar estas operaciones con gran flexibilidad, sin necesidad de utilizar formularios (EditForm o SubmitForm).

⚙️ ¿Qué es y para qué sirve Patch()?

Patch() sirve para insertar, modificar o combinar registros en una fuente de datos.

A diferencia de Collect() o SubmitForm(), ofrece un control total sobre qué campos se actualizan, cómo se manejan los valores, y qué sucede si un registro ya existe.

📌 Principales usos de Patch()

• Crear nuevos registros.
• Actualizar registros existentes.
• Modificar múltiples registros de forma dinámica (usando ForAll()).
• Actualizar colecciones locales sin conexión (Collections).
• Combinar datos entre múltiples fuentes.

🧠 Sintaxis

Patch(
    DataSource,
    BaseRecord,
    {ChangeRecord1 [, ChangeRecord2, ...]}
)

Parámetros:

• DataSource: Fuente de datos (SharePoint, Dataverse, Excel, Collection, etc.).
• BaseRecord: Registro a actualizar, o Defaults(DataSource) si se desea crear uno nuevo.
• ChangeRecord: Uno o más conjuntos de cambios que se aplicarán sobre el registro base.

🧩 Ejemplo 1 – Crear un nuevo registro

Imagina que tenemos una lista de SharePoint llamada Clientes con las columnas:

• Title (nombre del cliente)
• Email
• Teléfono

Podemos crear un nuevo registro con:

Patch(
    Clientes,
    Defaults(Clientes),
    {
        Title: TextInput_Nombre.Text,
        Email: TextInput_Email.Text,
        Telefono: TextInput_Telefono.Text
    }
)

💡En este ejemplo supongamos que tenemos 3 text inputs, uno para cada uno de los datos y estamos extrayendo el dato de cada control.

🧾 Explicación:

• Defaults(Clientes) genera un registro vacío basado en el esquema de la lista.
• Los valores provienen de los controles de texto.
• Patch guarda directamente el registro en la fuente de datos.

Usa el siguiente ejemplo para interactuar con el Sandbox:

Patch(
  Registros,
  Defaults(Registros),
  {
    Title:"",
    Email:"",
    Telefono:""
  }
)

🧩 Ejemplo 2 – Actualizar un registro existente

Si queremos actualizar el teléfono de un cliente según su correo electrónico:

Patch(
    Clientes,
    LookUp(Clientes, Email = TextInput_Email.Text),
    { Teléfono: TextInput_TelefonoNuevo.Text }
)

📌 En este caso, LookUp() encuentra el registro y Patch() actualiza solo el campo Teléfono.

💡 Lo que devuelve Patch()

Un detalle muy importante — y poco conocido por principiantes — es que Patch() devuelve un registro.

• Si la operación se realiza con éxito, devuelve el registro modificado o creado.
• Si ocurre un error, devuelve un valor en blanco y el error puede capturarse con IfError() o la función Errors().

Ejemplo práctico:

Set(
    varCliente,
    Patch(
        Clientes,
        Defaults(Clientes),
        { Title: "Juan Pérez", Email: "juan@ejemplo.com" }
    )
);
// Mostrar el nombre del registro creado
Label_Resultado.Text = varCliente.Title

💬 En este ejemplo, la variable varCliente almacena el registro recién creado, lo cual permite:

• Mostrar su información.
• Usarlo como referencia en otras operaciones (Navigate, UpdateContext, etc.).
• Validar si el registro se creó correctamente.

⚠️ Manejo de errores con IfError()

Puedes envolver la función Patch() para detectar fallos, por ejemplo:

IfError(
    Patch(
        Clientes,
        Defaults(Clientes),
        {
          Title: "",
          Email: "prueba@demo.com"
        }
    ),
    Notify(
        "Error al guardar el registro",
        NotificationType.Error
    ),
    Notify(
        "Registro guardado correctamente",
        NotificationType.Success
    )
)

👉 Esto es especialmente útil cuando trabajas con Dataverse o fuentes externas que requieren validaciones o permisos específicos.

🧰 Buenas prácticas

✅ Usa Defaults() para crear nuevos registros.
✅ Guarda el resultado de Patch() en una variable si planeas usarlo después.
✅ Aplica IfError() o Errors() para manejar fallos.
✅ Evita usar Patch() dentro de bucles intensivos en grandes volúmenes de datos (mejor usa ForAll() con moderación).
✅ Revisa los permisos del usuario en la fuente de datos antes de ejecutar Patch().

❌ Errores comunes

🚫 Olvidar el Defaults() al crear un registro nuevo.
🚫 Intentar actualizar campos que no existen o están bloqueados.
🚫 No manejar errores, lo que impide detectar fallos de guardado.
🚫 Usar Patch() con campos de búsqueda (lookups) sin definir correctamente los registros relacionados.

🔁 Variantes y combinaciones útiles

Actualizar varios registros a la vez:

ForAll(
    CollectionClientes,
    Patch(
        Clientes,
        LookUp(Clientes, ID = ThisRecord.ID),
        ThisRecord
    )
)

Combinar con Collect() para guardar datos localmente:

Collect(
    MisCambios,
    Patch(
        Clientes,
        Defaults(Clientes),
        {Title: "Nuevo"}
    )
)

📚 Recursos oficiales

🔗 Documentación oficial – Función Patch (Microsoft Learn)
🔗 Manejo de errores con IfError
🔗 ForAll y operaciones en lotes

🧩 Mini práctica recomendada

1. Crea una lista de SharePoint llamada Clientes.
2. Diseña un formulario simple con tres controles de texto: Nombre, Email, Teléfono.
3. Agrega un botón Guardar con el siguiente código:

Set(
    varResultado,
    IfError(
        Patch(Clientes, Defaults(Clientes),
            {
                Title: TextInput_Nombre.Text,
                Email: TextInput_Email.Text,
                Teléfono: TextInput_Telefono.Text
            }
        ),
        Notify("Error al guardar el registro.", NotificationType.Error),
        Notify("Registro guardado correctamente.", NotificationType.Success)
    )
);

4. Muestra en una etiqueta el valor de varResultado.Title para confirmar que Patch() devolvió el registro creado.