Esta documentación está archivada y no tiene mantenimiento.

FileUpload (Clase)

Actualización: noviembre 2007

Muestra un control de cuadro de texto y un botón de búsqueda que permiten a los usuarios seleccionar un archivo para cargarlo al servidor.

Espacio de nombres:  System.Web.UI.WebControls
Ensamblado:  System.Web (en System.Web.dll)

[ControlValuePropertyAttribute("FileBytes")]
[ValidationPropertyAttribute("FileName")]
[AspNetHostingPermissionAttribute(SecurityAction.LinkDemand, Level = AspNetHostingPermissionLevel.Minimal)]
[AspNetHostingPermissionAttribute(SecurityAction.InheritanceDemand, Level = AspNetHostingPermissionLevel.Minimal)]
public class FileUpload : WebControl
/** @attribute ControlValuePropertyAttribute("FileBytes") */
/** @attribute ValidationPropertyAttribute("FileName") */
/** @attribute AspNetHostingPermissionAttribute(SecurityAction.LinkDemand, Level = AspNetHostingPermissionLevel.Minimal) */
/** @attribute AspNetHostingPermissionAttribute(SecurityAction.InheritanceDemand, Level = AspNetHostingPermissionLevel.Minimal) */
public class FileUpload extends WebControl
public class FileUpload extends WebControl
<asp:FileUpload />

La clase FileUpload muestra un control de cuadro de texto y un botón de búsqueda que permiten a los usuarios seleccionar un archivo en el cliente y cargarlo en el servidor web. El usuario especifica el archivo que desea cargar escribiendo su ruta de acceso completa en el equipo local (por ejemplo, C:\MisArchivos\ArchivoPrueba.txt) en el cuadro de texto del control. También puede seleccionar el archivo haciendo clic en el botón Examinar y buscándolo después en el cuadro de diálogo Elegir archivo.

ysf0192b.alert_note(es-es,VS.90).gifNota:

El control FileUpload está diseñado para utilizarse sólo en escenarios de devolución de datos y no en escenarios de devolución de datos asincrónica durante la representación parcial de la página. Al utilizar un control FileUpload dentro de un control UpdatePanel, el archivo se debe cargar utilizando un control que es un objeto PostBackTrigger del panel. Los controles UpdatePanel se utilizan para actualizar regiones seleccionadas de una página en lugar de actualizar toda la página con una devolución de datos. Para obtener más información, vea Información general sobre el control UpdatePanel y Información general sobre la representación parcial de páginas.

El control FileUpload no guarda automáticamente un archivo en el servidor después de que el usuario lo seleccione para cargarlo. Debe proporcionar explícitamente un control o un mecanismo que permita al usuario enviar el archivo especificado. Por ejemplo, proporcione un botón donde el usuario pueda hacer clic para cargar el archivo. El código que escriba para guardar el archivo especificado debe llamar al método SaveAs, que guarda el contenido de un archivo en una ruta especificada del servidor. Normalmente, se llama al método SaveAs en un método de control de eventos para un evento que inicia una devolución de datos al servidor. Por ejemplo, si se proporciona un botón para enviar un archivo, podría incluir el código para guardar el archivo en el método de control de eventos del evento clic.

Antes de llamar al método SaveAs para guardar el archivo en el servidor, compruebe por medio de la propiedad HasFile si el control FileUpload contiene un archivo. Si la propiedad HasFile devuelve true, llame al método SaveAs. Si devuelve false, muestra un mensaje al usuario que indica que el control no contiene un archivo. No compruebe la propiedad PostedFile para averiguar si existe un archivo para cargar, porque esta propiedad contiene de manera predeterminada 0 bytes. Como consecuencia, la propiedad PostedFile devuelve un valor no nulo aunque el control FileUpload esté en blanco.

Cuando llame al método SaveAs, especifique la ruta de acceso completa del directorio en el que deba guardarse el archivo cargado. Si no especifica explícitamente una ruta de acceso en el código de su aplicación, se producirá una excepción cuando un usuario intente cargar un archivo. Este comportamiento ayuda a mantener seguros los archivos del servidor, al impedir que los usuarios puedan escribir en ubicaciones arbitrarias de la estructura de directorios de la aplicación y, a la vez, evitar el acceso a los directorios raíz confidenciales.

El método SaveAs escribe el archivo cargado en el directorio especificado. Por consiguiente, la aplicación ASP.NET debe tener derechos de escritura en el directorio del servidor. La aplicación dispone de dos medios para obtener acceso de escritura. Se puede otorgar explícitamente acceso de escritura a la cuenta bajo la cual se ejecuta la aplicación, en el directorio donde desee guardar los archivos cargados. O bien, puede aumentar el nivel de confianza que se concede a la aplicación ASP.NET. Para obtener acceso de escritura al directorio de ejecución de la aplicación, ésta debe otorgar al objeto AspNetHostingPermission un nivel de confianza establecido en el valor AspNetHostingPermissionLevel.Medium. Un aumento del nivel de confianza aumenta el acceso de la aplicación a los recursos del servidor. Tenga en cuenta que esta estrategia no es segura, puesto que un usuario malintencionado que se haga con el control de la aplicación también podrá trabajar con este nivel de confianza superior. El procedimiento recomendado es ejecutar una aplicación ASP.NET en el contexto de un usuario con los privilegios mínimos necesarios para que se ejecute la aplicación. Para obtener más información acerca de la seguridad en aplicaciones ASP.NET, vea Procedimientos de seguridad básicos para aplicaciones Web y Niveles de confianza y archivos de directivas de ASP.NET.

Utilice la propiedad FileName para obtener el nombre de un archivo de un cliente que desee cargar utilizando el control FileUpload. El nombre de archivo que devuelve esta propiedad no incluye la ruta de acceso del archivo en el cliente.

La propiedad FileContent obtiene un objeto Stream que señala a un archivo para cargarlo. Utilice esta propiedad para obtener acceso al contenido del archivo en forma de bytes. Por ejemplo, puede usar el objeto Stream devuelto por la propiedad FileContent para leer el contenido del archivo en forma de bytes y almacenarlo en una matriz de bytes. O bien, puede utilizar la propiedad FileBytes para recuperar todos los bytes del archivo.

La propiedad PostedFile obtiene el objeto HttpPostedFile subyacente para el archivo que se va a cargar. Puede utilizar esta propiedad para tener acceso a otras propiedades del archivo. La propiedad ContentLength obtiene la longitud del archivo. La propiedad ContentType obtiene el tipo de contenido MIME del archivo. También puede utilizar la propiedad PostedFile para obtener acceso a la propiedad FileName, la propiedad InputStream y el método SaveAs. Por otro lado, la propiedad FileName, la propiedad FileContent y el método SaveAs proporcionan la misma funcionalidad.

Un procedimiento para protegerse de los ataques por denegación de servicio consiste en limitar el tamaño de los archivos que pueden cargarse por medio del control FileUpload. Establezca un límite de tamaño que sea adecuado para los tipos de archivos que prevea que se cargarán. El límite de tamaño predeterminado es 4096 kilobytes (KB) o 4 megabytes (MB). Puede permitir la carga de archivos mayores estableciendo el atributo maxRequestLength del elemento httpRuntime. Para aumentar el tamaño máximo de archivo permitido para la aplicación completa, defina el atributo maxRequestLength en el archivo Web.config. Para aumentar el tamaño máximo de archivo permitido para una página determinada, defina el atributo maxRequestLength en el elemento location del archivo Web.config. Si desea un ejemplo, vea Elemento location (Esquema de configuración de ASP.NET).

Durante la carga de archivos grandes, un usuario también podría recibir el mensaje de error siguiente:

aspnet_wp.exe (PID: 1520) was recycled because memory consumption exceeded 460 MB (60 percent of available RAM).

Si los usuarios reciben este mensaje de error, aumente el valor del atributo memoryLimit en el elemento processModel del archivo Web.config de la aplicación. El atributo memoryLimit especifica la cantidad de memoria máxima que puede utilizar un proceso de trabajo. Si el proceso de trabajo rebasa la cantidad especificada por memoryLimit, se crea un proceso nuevo para reemplazarlo, y se reasignan todas las solicitudes actuales al nuevo proceso.

Puede controlar si el archivo cargado se almacena temporalmente en la memoria o en el servidor, mientras se procesa la solicitud, estableciendo el atributo requestLengthDiskThreshold del elemento httpRuntime. Este atributo permite administrar el tamaño del búfer de la secuencia de entrada. El valor predeterminado es 256 bytes. El valor especificado no debe exceder del valor especificado para el atributo maxRequestLength.

TopicLocation
Cómo: Cargar archivos con el control FileUpload de servidor WebGenerar aplicaciones Web ASP .NET en Visual Studio
Cómo: Establecer el foco en los controles de servidor Web ASP.NETGenerar aplicaciones Web ASP .NET en Visual Studio
Cómo: Establecer el foco en los controles de servidor Web ASP.NETGenerar aplicaciones Web ASP .NET
Cómo: Cargar archivos con el control FileUpload de servidor WebGenerar aplicaciones Web ASP .NET
Cómo: Cargar archivos con el control FileUpload de servidor WebGenerar aplicaciones Web ASP .NET en Visual Studio
Cómo: Establecer el foco en los controles de servidor Web ASP.NETGenerar aplicaciones Web ASP .NET en Visual Studio

Esta sección contiene los cuatro ejemplos siguientes:

  • En el primer ejemplo se muestra cómo crear un control FileUpload que guarda los archivos en una ruta de acceso que se especifica en el código.

  • En el segundo ejemplo se muestra cómo crear un control FileUpload que guarda los archivos en un directorio especificado del sistema de archivos de la aplicación.

  • En el tercer ejemplo se muestra cómo crear un control FileUpload que guarda los archivos en una ruta de acceso especificada y limita el tamaño de los archivos que pueden cargarse.

  • En el cuarto ejemplo se muestra cómo crear un control FileUpload que guarda los archivos en una ruta de acceso especificada y sólo permite cargar archivos con la extensión .doc o .xls.

ysf0192b.alert_caution(es-es,VS.90).gifPrecaución:

Estos ejemplos muestran la sintaxis básica del control FileUpload, pero no todos los procedimientos de comprobación de errores necesarios que deben realizarse antes de guardar el archivo. Para obtener un ejemplo más completo, vea SaveAs.

En el ejemplo siguiente se muestra cómo crear un control FileUpload que guarda los archivos en una ruta de acceso que se especifica en el código. Se llama al método SaveAs para guardar el archivo en la ruta de acceso especificada en el servidor.

<%@ Page Language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 

<script runat="server">

  protected void UploadButton_Click(object sender, EventArgs e)
  {
    // Specify the path on the server to
    // save the uploaded file to.
    String savePath = @"c:\temp\uploads\";

    // Before attempting to perform operations
    // on the file, verify that the FileUpload 
    // control contains a file.
    if (FileUpload1.HasFile)
    {
      // Get the name of the file to upload.
      String fileName = FileUpload1.FileName;

      // Append the name of the file to upload to the path.
      savePath += fileName;


      // Call the SaveAs method to save the 
      // uploaded file to the specified path.
      // This example does not perform all
      // the necessary error checking.               
      // If a file with the same name
      // already exists in the specified path,  
      // the uploaded file overwrites it.
      FileUpload1.SaveAs(savePath);

      // Notify the user of the name of the file
      // was saved under.
      UploadStatusLabel.Text = "Your file was saved as " + fileName;
    }
    else
    {      
      // Notify the user that a file was not uploaded.
      UploadStatusLabel.Text = "You did not specify a file to upload.";
    }

  }
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>FileUpload Example</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
       <h4>Select a file to upload:</h4>

       <asp:FileUpload id="FileUpload1"                 
           runat="server">
       </asp:FileUpload>

       <br /><br />

       <asp:Button id="UploadButton" 
           Text="Upload file"
           OnClick="UploadButton_Click"
           runat="server">
       </asp:Button>    

       <hr />

       <asp:Label id="UploadStatusLabel"
           runat="server">
       </asp:Label>        
    </div>
    </form>
</body>
</html>


En el ejemplo siguiente se muestra cómo crear un control FileUpload que guarda los archivos en un directorio especificado del sistema de archivos de la aplicación. La propiedad HttpRequest.PhysicalApplicationPath permite obtener la ruta física del sistema de archivos del directorio raíz para la aplicación de servidor actualmente ejecutada. Se llama al método SaveAs para guardar el archivo en la ruta de acceso especificada en el servidor.

<%@ Page Language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<script runat="server">

    protected void UploadButton_Click(object sender, EventArgs e)
    {
        // Save the uploaded file to an "Uploads" directory
        // that already exists in the file system of the 
        // currently executing ASP.NET application.  
        // Creating an "Uploads" directory isolates uploaded 
        // files in a separate directory. This helps prevent
        // users from overwriting existing application files by
        // uploading files with names like "Web.config".
        string saveDir = @"\Uploads\";

        // Get the physical file system path for the currently
        // executing application.
        string appPath = Request.PhysicalApplicationPath;

        // Before attempting to save the file, verify
        // that the FileUpload control contains a file.
        if (FileUpload1.HasFile)
        {
            string savePath = appPath + saveDir +
                Server.HtmlEncode(FileUpload1.FileName);

            // Call the SaveAs method to save the 
            // uploaded file to the specified path.
            // This example does not perform all
            // the necessary error checking.               
            // If a file with the same name
            // already exists in the specified path,  
            // the uploaded file overwrites it.
            FileUpload1.SaveAs(savePath);

            // Notify the user that the file was uploaded successfully.
            UploadStatusLabel.Text = "Your file was uploaded successfully.";

        }
        else
        {
            // Notify the user that a file was not uploaded.
            UploadStatusLabel.Text = "You did not specify a file to upload.";   
        }
    }
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>FileUpload Class Example</title>
</head>
<body>
    <h3>FileUpload Class Example: Save To Application Directory</h3>
    <form id="form1" runat="server">
    <div>
       <h4>Select a file to upload:</h4>

       <asp:FileUpload id="FileUpload1"                 
           runat="server">
       </asp:FileUpload>

       <br/><br/>

       <asp:Button id="UploadButton" 
           Text="Upload file"
           OnClick="UploadButton_Click"
           runat="server">
       </asp:Button>    

       <hr />

       <asp:Label id="UploadStatusLabel"
           runat="server">
       </asp:Label>           
    </div>
    </form>
</body>
</html>


En el ejemplo siguiente se muestra cómo crear un control FileUpload que guarda los archivos en una ruta de acceso que se especifica en el código. El control limita el tamaño de archivo que se puede cargar a 5 MB. La propiedad PostedFile se utiliza para obtener acceso a la propiedad ContentLength subyacente y devolver el tamaño del archivo. Si el tamaño del archivo que se carga es inferior a 2 MB, se llama al método SaveAs para guardarlo en la ruta especificada del servidor. Además de comprobar la configuración de tamaño máximo de archivo en el código de la aplicación, puede establecer el atributo maxRequestLength del elemento httpRuntime en un tamaño máximo permitido, en el archivo de configuración de la aplicación.

<%@ Page Language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<script runat="server">

    protected void UploadButton_Click(object sender, EventArgs e)
    {
        // Specify the path on the server to
        // save the uploaded file to.
        string savePath = @"c:\temp\uploads\";

        // Before attempting to save the file, verify
        // that the FileUpload control contains a file.
        if (FileUpload1.HasFile)
        {                
            // Get the size in bytes of the file to upload.
            int fileSize = FileUpload1.PostedFile.ContentLength;

            // Allow only files less than 2,100,000 bytes (approximately 2 MB) to be uploaded.
            if (fileSize < 2100000)
            {

                // Append the name of the uploaded file to the path.
                savePath += Server.HtmlEncode(FileUpload1.FileName);

                // Call the SaveAs method to save the 
                // uploaded file to the specified path.
                // This example does not perform all
                // the necessary error checking.               
                // If a file with the same name
                // already exists in the specified path,  
                // the uploaded file overwrites it.
                FileUpload1.SaveAs(savePath);

                // Notify the user that the file was uploaded successfully.
                UploadStatusLabel.Text = "Your file was uploaded successfully.";
            }
            else
            {
                // Notify the user why their file was not uploaded.
                UploadStatusLabel.Text = "Your file was not uploaded because " + 
                                         "it exceeds the 2 MB size limit.";
            }
        }   
        else
        {
            // Notify the user that a file was not uploaded.
            UploadStatusLabel.Text = "You did not specify a file to upload.";
        }
    }
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>FileUpload Class Example</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
       <h4>Select a file to upload:</h4>

       <asp:FileUpload id="FileUpload1"                 
           runat="server">
       </asp:FileUpload>

       <br/><br/>

       <asp:Button id="UploadButton" 
           Text="Upload file"
           OnClick="UploadButton_Click"
           runat="server">
       </asp:Button>

       <hr />

       <asp:Label id="UploadStatusLabel"
           runat="server">
       </asp:Label>

    </div>
    </form>
</body>
</html>


En el ejemplo siguiente se muestra cómo crear un control FileUpload que guarda los archivos en una ruta de acceso que se especifica en el código. Este ejemplo sólo permite cargar archivos con la extensión .doc o .xls. Se llama al método Path.GetExtension para devolver la extensión del archivo que se carga. Si el archivo tiene una extensión .doc o .xls, se llama al método SaveAs para guardarlo en la ruta especificada del servidor.

<%@ Page Language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<script runat="server">

    protected void UploadBtn_Click(object sender, EventArgs e)
    {
        // Specify the path on the server to
        // save the uploaded file to.
        string savePath = @"c:\temp\uploads";

        // Before attempting to save the file, verify
        // that the FileUpload control contains a file.
        if (FileUpload1.HasFile)
        {
            // Get the name of the file to upload.
            string fileName = Server.HtmlEncode(FileUpload1.FileName);

            // Get the extension of the uploaded file.
            string extension = System.IO.Path.GetExtension(fileName);

            // Allow only files with .doc or .xls extensions
            // to be uploaded.
            if ((extension == ".doc") | (extension == ".xls"))
            {
                // Append the name of the file to upload to the path.
                savePath += fileName;

                // Call the SaveAs method to save the 
                // uploaded file to the specified path.
                // This example does not perform all
                // the necessary error checking.               
                // If a file with the same name
                // already exists in the specified path,  
                // the uploaded file overwrites it.
                FileUpload1.SaveAs(savePath);

                // Notify the user that their file was successfully uploaded.
                UploadStatusLabel.Text = "Your file was uploaded successfully.";
            }
            else
            {
                // Notify the user why their file was not uploaded.
                UploadStatusLabel.Text = "Your file was not uploaded because " + 
                                         "it does not have a .doc or .xls extension.";
            }

        }

    }

</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title>FileUpload Class Example</title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
        <h4>Select a file to upload:</h4>

        <asp:FileUpload id="FileUpload1"                 
            runat="server">
        </asp:FileUpload>

        <br/><br/>

        <asp:Button id="UploadBtn" 
            Text="Upload file"
            OnClick="UploadBtn_Click"
            runat="server">
        </asp:Button>    

        <hr />

        <asp:Label id="UploadStatusLabel"
            runat="server">
        </asp:Label>     
    </div>
    </form>
</body>
</html>


Todos los miembros static (Shared en Visual Basic) públicos de este tipo son seguros para la ejecución de subprocesos. No se garantiza que los miembros de instancias sean seguros para la ejecución de subprocesos.

Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

.NET Framework y .NET Compact Framework no admiten todas las versiones de cada plataforma. Para obtener una lista de las versiones compatibles, vea Requisitos de sistema de .NET Framework.

.NET Framework

Compatible con: 3.5, 3.0, 2.0
Mostrar: