Conceptos básicos de Blazor de ASP.NET Core

  • Artículo

Nota

Esta no es la versión más reciente de este artículo. Para la versión actual, consulte la versión .NET 8 de este artículo.

Importante

Esta información hace referencia a un producto en versión preliminar, el cual puede sufrir importantes modificaciones antes de que se publique la versión comercial. Microsoft no proporciona ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí.

Para la versión actual, consulte la versión .NET 8 de este artículo.

En los artículos de los conceptos básicos se proporcionan instrucciones sobre los conceptos de Blazor básicos. Algunos de los conceptos están conectados a un conocimiento básico de los componentes de Razor, que se describen más adelante en la siguiente sección de este artículo y se tratan con detalle en los artículos de los componentes.

Conceptos de representación de cliente y servidor

En toda la documentación de Blazor, se dice que la actividad que tiene lugar en el sistema del usuario se produce en el cliente o en el lado cliente. Se dice que la actividad que tiene lugar en un servidor se produce en el servidor o en el lado servidor.

El término representación significa generar el marcado HTML que muestran los exploradores.

  • La representación del lado cliente (CSR) significa que el entorno de ejecución de Blazor WebAssembly genera el marcado HTML final. En este tipo de representación, no se envía ningún código HTML para la interfaz de usuario generada por el cliente de la aplicación de un servidor al cliente. Se supone que la interactividad del usuario con la página. No hay ningún concepto como la representación estática del lado cliente. Se supone que la CSR es interactiva, por lo que "representación del lado del cliente interactiva" y "CSR interactiva" no se usan en el sector ni en la documentación de Blazor.

  • La representación del lado servidor (SSR) significa que el entorno de ejecución de ASP.NET Core genera el marcado HTML final. El código HTML se envía al cliente a través de una red para que lo muestre el explorador del cliente. En este tipo de representación, el cliente no crea ningún código HTML para la interfaz de usuario generada por el servidor de la aplicación. SSR puede ser de dos variedades:

    • SSR estático: el servidor produce HTML estático que no prevé la interactividad del usuario ni el mantenimiento del estado de los componentes de Razor.
    • SSR interactivo: los eventos de Blazor permiten la interactividad del usuario y el estado de los componentes de Razor es mantenido por el marco Blazor.

  • La representación previa es el proceso de representación inicial del contenido de la página en el servidor sin habilitar controladores de eventos para controles representados. El servidor genera la interfaz de usuario HTML de la página lo antes posible en respuesta a la solicitud inicial, lo que hace que la aplicación se sienta más sensible a los usuarios. La representación previa también puede mejorar la optimización del motor de búsqueda (SEO) mediante la representación del contenido de la respuesta HTTP inicial que los motores de búsqueda usan para calcular la clasificación de página. La representación previa siempre va seguida de la representación final, ya sea en el servidor o en el cliente.

Conceptos de representación estática e interactiva

Los componentes de Razor se representan estáticamente o interactivamente.

Estática o representación estática es un escenario del lado servidor que significa que el componente se representa sin la capacidad de interacción entre el usuario y el código de .NET o C#. Los eventos DOM de JavaScript y HTML no se ven afectados, pero no se puede procesar ningún evento de usuario en el cliente cuando .NET se ejecuta en el servidor.

Interactiva o representación interactiva significa que el componente tiene la capacidad de procesar eventos .NET mediante código de C#. El entorno de ejecución de ASP.NET Core procesa los eventos .NET en el servidor o en el explorador del cliente mediante el entorno de ejecución de Blazor basado en WebAssembly.

Se puede encontrar más información sobre estos conceptos y cómo controlar la representación estática e interactiva en el artículo Modos de representaciónBlazor de ASP.NET Core más adelante en la documentación de Blazor.

Componentes Razor

Las aplicaciones Blazor se basan en componentes de Razor, a menudo conocidos simplemente como componentes. Un componente es un elemento de la interfaz de usuario, como una página, un cuadro de diálogo o un formulario de entrada de datos. Los componentes son clases C# de .NET integradas en ensamblados de .NET.

Razor hace referencia a cómo se escriben normalmente los componentes en forma de página de marcado de Razor para la composición y la lógica de la interfaz de usuario del lado cliente. Razor es una sintaxis para combinar marcado HTML con código de C# diseñada para aumentar la productividad del desarrollador. Los archivos de Razor usan la extensión de archivo .razor.

Aunque algunos desarrolladores y recursos en línea de Blazor usan el término "componentes de Blazor", la documentación evita dicho término y usa universalmente "componentes de Razor" o "componentes".

En la documentación de Blazor se adoptan varias convenciones para mostrar y hablar sobre los componentes:

  • Código del proyecto, rutas de acceso y nombres de archivo, nombres de plantilla de proyecto y otros términos especializados están en inglés de Estados Unidos y aparecen entre código.
  • Normalmente se hace referencia a los componentes mediante su nombre de clase de C# (Pascal case) seguido de la palabra "componente". Por ejemplo, un componente de carga de archivos típico se conoce como "componente FileUpload".
  • Normalmente, el nombre de clase de C# de un componente es el mismo que su nombre de archivo.
  • Los componentes enrutables suelen establecer sus direcciones URL relativas en el nombre de clase del componente con grafía kebab. Por ejemplo, un componente FileUpload incluye la configuración de enrutamiento para acceder al componente representado en la dirección URL relativa /file-upload. El enrutamiento y la navegación se tratan en Enrutamiento y navegación de Blazor de ASP.NET Core.
  • Cuando se usan varias versiones de un componente, se numeran secuencialmente. Por ejemplo, se alcanza el componente FileUpload3 en /file-upload-3.
  • Razor Las directivas de la parte superior de una definición de componente (.razor file) se colocan en el orden siguiente: @page, @rendermode (.NET 8 o posterior), @using instrucciones, otras directivas en orden alfabético. Se encuentra información adicional sobre Razor el orden de directivas en la sección deRazor sintaxis de ASP.NETRazor componentes principales.
  • Los modificadores de acceso se usan en ejemplos de artículos. Por ejemplo, los campos son private de forma predeterminada, pero están presentes explícitamente en el código de componente. Por ejemplo, private se especifica para declarar un campo llamado maxAllowedFiles como private int maxAllowedFiles = 3;.
  • Los valores de parámetro de componente tienen como prefijo un Razor símbolo @ reservado, pero no es necesario. Los literales (por ejemplo, valores booleanos), las palabras clave (por ejemplo, this) y null como valores de parámetro de componente no tienen el prefijo @, pero esto también es simplemente una convención de documentación. En el código propio puede usar el prefijo @ en los literales si lo desea.
  • Por lo general, los ejemplos siguen las instrucciones de ingeniería y las convenciones de código de C# o ASP.NET Core. Para obtener más información, consulte los siguientes recursos:

A continuación se muestra un componente de contador de ejemplo y parte de una aplicación creada a partir de una plantilla de proyecto Blazor. Una cobertura de componentes detallada se encuentra en los artículos de los componentes más adelante en la documentación. En el ejemplo siguiente se muestran los conceptos de componentes que se ven en los artículos de los conceptos básicos antes de acceder a los artículos de los componentes más adelante en la documentación.

Counter.razor:

El componente supone que un modo de representación interactivo se hereda de un componente primario o se aplica globalmente a la aplicación.

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

El componente Counter anterior:

  • Establece su ruta con la directiva @page en la primera línea.
  • Establece el título y el encabezado de la página.
  • Representa el recuento actual con @currentCount. currentCount es una variable de entero definida en el código de C# del bloque @code.
  • Muestra un botón para desencadenar el método IncrementCount, que también se encuentra en el bloque @code y aumenta el valor de la variable currentCount.

Modos de representación

Los artículos del nodo Aspectos básicos hacen referencia al concepto de modos de representación. Este tema se trata en profundidad en el artículo Modos de representación Blazorde ASP.NET Core del nodo Componentes, que aparece después del nodo Aspectos básicos de artículos.

Para conocer las primeras referencias en este nodo de artículos a los conceptos de modo de representación, basta con señalar lo siguiente en este momento:

Cada componente de una aplicación web de Blazor adopta un modo de representación para determinar el modelo de hospedaje que usa, dónde se representa y si se representa estáticamente en el servidor, se representa para la interactividad del usuario en el servidor o se representa para la interactividad del usuario en el cliente (normalmente con representación previa en el servidor).

Las aplicaciones Blazor Server y Blazor WebAssembly para las versiones de ASP.NET Core anteriores a .NET 8 permanecen centradas en los conceptos de modelo de hospedaje, no en los modos de representación. Los modos de representación se aplican conceptualmente a Blazor Web Apps en .NET 8 o posterior.

En la tabla siguiente se muestran los modos de representación disponibles para representar componentes Razor en una aplicación web Blazor. Los modos de representación se aplican a componentes con la directiva @rendermode de la instancia del componente o de la definición del componente. También es posible establecer un modo de representación para toda la aplicación.

Nombre Descripción Ubicación de representación Interactive
Servidor estático Representación estática del lado servidor (SSR estática) Servidor
Servidor interactivo Representación interactiva del lado servidor (SSR interactiva) mediante Blazor Server Servidor
WebAssembly interactivo Representación del lado cliente (CSR) mediante Blazor WebAssembly† Remoto
Automático interactivo SSR interactiva mediante Blazor Server inicialmente y, a continuación, CSR en las visitas posteriores después de descargar la agrupación de Blazor Servidor y, a continuación, cliente

†Se supone que la representación del lado cliente (CSR) es interactiva. La "representación interactiva del lado cliente" y la "CSR interactiva " no se usan en el sector ni en la documentación de Blazor.

La información anterior sobre los modos de representación es todo lo que necesita saber para comprender los artículos del nodo Aspectos básicos. Si no está familiarizado con Blazor y es la primera vez que lee artículos sobre Blazor en orden bajando por el índice, puede demorar el consumo de información en profundidad sobre los modos de representación hasta que llegue al artículo Modos de representación de BlazorASP.NET Core del nodo Componentes.

Document Object Model (DOM)

Las referencias al Document Object Model usan la abreviatura DOM.

Para obtener más información, vea los siguientes recursos:

Subconjunto de API de .NET para aplicaciones de Blazor WebAssembly

No está disponible una lista seleccionada de API específicas de .NET que se admiten en el explorador para Blazor WebAssembly. Sin embargo, puede buscar manualmente una lista de API de .NET anotadas con [UnsupportedOSPlatform("browser")] para detectar las API de .NET que no se admiten en WebAssembly.

Nota:

Los vínculos de la documentación al origen de referencia de .NET cargan normalmente la rama predeterminada del repositorio, que representa el desarrollo actual para la próxima versión de .NET. Para seleccionar una etiqueta de una versión específica, use la lista desplegable Cambiar ramas o etiquetas. Para obtener más información, vea Procedimientos para seleccionar una etiqueta de versión de código fuente de ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Para obtener más información, consulte los siguientes recursos:

Aplicaciones de muestra

Las aplicaciones de ejemplo de la documentación están disponibles para su inspección y descarga:

Repositorio de GitHub con ejemplos de Blazor (dotnet/blazor-samples)

Busque una aplicación de ejemplo seleccionando primero la carpeta de versión que coincida con la versión de .NET con la que está trabajando.

Aplicaciones de ejemplo en el repositorio:

El repositorio de ejemplo contiene dos tipos de ejemplos:

  • Las aplicaciones de ejemplo de fragmento de código proporcionan los ejemplos de código que aparecen en los artículos. Estas aplicaciones se compilan, pero no son necesariamente aplicaciones ejecutables. Estas aplicaciones son útiles para obtener simplemente código de ejemplo que aparece en artículos.
  • Las aplicaciones de ejemplo que acompañan a los artículos de Blazor se compilan y ejecutan en los siguientes escenarios:
    • Blazor Server con EF Core
    • Blazor Server y Blazor WebAssembly con SignalR
    • Registro habilitado para ámbitos de Blazor WebAssembly

Para obtener más información, consulte el repositorio de GitHub de ejemplos Blazor archivo README.md.

La aplicación de prueba básica del repositorio ASP.NET Core también es un conjunto útil de ejemplos para varios escenarios Blazor:

BasicTestApp en ASP.NET origen de referencia principal (dotnet/aspnetcore)

Nota

Los vínculos de la documentación al origen de referencia de .NET cargan normalmente la rama predeterminada del repositorio, que representa el desarrollo actual para la próxima versión de .NET. Para seleccionar una etiqueta de una versión específica, use la lista desplegable Cambiar ramas o etiquetas. Para obtener más información, vea Procedimientos para seleccionar una etiqueta de versión de código fuente de ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Para descargar las aplicaciones de ejemplo:

Múltiplos de byte

Los tamaños de bytes de .NET usan prefijos de métrica para múltiplos no decimal de bytes en función de las potencias de 1024.

Nombre (abreviatura) Tamaño Ejemplo
Kilobyte (KB) 1024 bytes 1 KB = 1024 bytes
Megabyte (MB) 10242 bytes 1 MB = 1 048 576 bytes
Gigabytes (GB) 10243 bytes 1 GB = 1 073 741 824 bytes

Solicitudes de soporte técnico

Solo los problemas relacionados con la documentación son adecuados para el repositorio dotnet/AspNetCore.Docs. Para obtener soporte técnico de productos, no abra un problema relativo a la documentación. Busque ayuda a través de uno o varios de los siguientes canales de soporte técnico:

En caso de producirse un error potencial en los comentarios sobre el marco o el producto, abra un problema para la unidad de producto de ASP.NET Core en dotnet/aspnetcore issues. Los informes de errores suelen requerir lo siguiente:

  • Explicación clara del problema: siga las instrucciones de la plantilla de problemas de GitHub proporcionada por la unidad de producto al abrirse un problema.
  • Proyecto de reproducción mínimo: coloque un proyecto en GitHub que los ingenieros de unidad de producto descarguen y ejecuten. Vincule el proyecto de forma cruzada al comentario de apertura del problema.

En caso de producirse un problema potencial con un artículo de Blazor, abra un problema relativo a la documentación. Para abrir un problema relativo a la documentación, use el botón de comentarios Esta página y el formulario de la parte inferior del artículo, y deje los metadatos en su lugar correspondiente al crear el comentario de apertura. Los metadatos proporcionan datos de seguimiento y hacen ping automáticamente al creador del artículo. Si se ha tratado el asunto con la unidad de producto, sitúe un vínculo cruzado al problema de ingeniería en el comentario de apertura del problema con la documentación.

Para notificar problemas o comentarios sobre Visual Studio, use los gestos de Notificar un problema o Sugerir una característica desde Visual Studio, los cuales abren incidencias internas para Visual Studio. Para más información, consulte Comentarios de Visual Studio.

Si tiene problemas con Visual Studio Code, solicite soporte técnico en los foros de soporte técnico de la comunidad. Para notificar informes de errores y comentarios, abra un problema en el repositorio de GitHub microsoft/vscode.

Los problemas de GitHub relativos a la documentación de Blazor se marcan automáticamente para la evaluación de propiedades en el proyecto Blazor.Docs (repositorio de GitHub dotnet/AspNetCore.Docs). Espere un poco para obtener una respuesta, especialmente durante los fines de semana y los días festivos. Normalmente, los creadores de la documentación responden en un plazo de 24 horas los días laborables.

Para obtener una colección de vínculos a los recursos de Blazor mantenidos por la comunidad, visite Awesome Blazor.

Nota

Microsoft no posee, mantiene ni admite Awesome Blazor, así como la mayoría de los productos y servicios de la comunidad descritos y vinculados allí.