.NET Framework 4 Gacutil.exe (Global Assembly Cache Tool) Updated: April 2011 The Global Assembly Cache tool allows you to view and manipulate the contents of the global assembly cache and download cache. This tool is automatically installed with Visual Studio and with the Windows SDK. To run the tool, we recommend that you use the Visual Studio Command Prompt or the Windows SDK Command Prompt (CMD Shell). These utilities enable you to run the tool easily, without navigating to the installation folder. For more information, see Visual Studio and Windows SDK Command Prompts. If you have Visual Studio installed on your computer: On the taskbar, click Start, click All Programs, click Visual Studio, click Visual Studio Tools, and then click Visual Studio Command Prompt. -or- If you have the Windows SDK installed on your computer: On the taskbar, click Start, click All Programs, click the folder for the Windows SDK, and then click Command Prompt (or CMD Shell). At the command prompt, type the following:
gacutil [options] [assemblyName | assemblyPath | assemblyListFile]
Parameters
Argument | Description |
|---|
assemblyName | The name of an assembly. You can supply either a partially specified assembly name such as myAssembly or a fully specified assembly name such as myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5. | assemblyPath | The name of a file that contains an assembly manifest. | assemblyListFile | The path to an ANSI text file that lists assemblies to install or uninstall. To use a text file to install assemblies, specify the path to each assembly on a separate line in the file. The tool interprets relative paths, relative to the location of the assemblyListFile. To use a text file to uninstall assemblies, specify the fully qualified assembly name for each assembly on a separate line in the file. See the assemblyListFile contents examples later in this topic. |
Option | Description |
|---|
/cdl | Deletes the contents of the download cache. | /f | Specify this option with the /i or /il options to force an assembly to reinstall. If an assembly with the same name already exists in the global assembly cache, the tool overwrites it. | /h[elp] | Displays command syntax and options for the tool. | /i assemblyPath | Installs an assembly into the global assembly cache. | /if assemblyPath | Installs an assembly into the global assembly cache. If an assembly with the same name already exists in the global assembly cache, the tool overwrites it. Specifying this option is equivalent to specifying the /i and /f options together. | /il assemblyListFile | Installs one or more assemblies specified in assemblyListFile into the global assembly cache. | /ir assemblyPath scheme id description | Installs an assembly into the global assembly cache and adds a reference to count the assembly. You must specify the assemblyPath, scheme, id,and description parameters with this option. For a description of the valid values you can specify for these parameters, see the /r option. Specifying this option is equivalent to specifying the /i and /r options together. | /l [assemblyName] | Lists the contents of the global assembly cache. If you specify the assemblyName parameter, the tool lists only the assemblies matching that name. | /ldl | Lists the contents of the downloaded files cache. | /lr [assemblyName] | Lists all assemblies and their corresponding reference counts. If you specify the assemblyName parameter, the tool lists only the assemblies matching that name and their corresponding reference counts. | /nologo | Suppresses the Microsoft startup banner display. | /r [assemblyName | assemblyPath] scheme id description | Specifies a traced reference to an assembly or assemblies to install or uninstall. Specify this option with the /i, /il, /u, or /ul options. To install an assembly, specify the assemblyPath, scheme, id,and description parameters with this option. To uninstall an assembly, specify the assemblyName, scheme, id,and description parameters. To remove a reference to an assembly, you must specify the same scheme, id, and description parameters that were specified with the /i and /r (or /ir) options when the assembly was installed. If you are uninstalling an assembly, the tool also removes the assembly from the global assembly cache if it is the last reference to remove and if Windows Installer has no outstanding references to the assembly. The scheme parameter specifies the type of installation scheme. You can specify one of the following values: UNINSTALL_KEY: Specify this value if the installer adds the application to Add/Remove Programs in Microsoft Windows. Applications add themselves to Add/Remove Programs by adding a registry key to HKLM\Software\Microsoft\Windows\CurrentVersion. FILEPATH: Specify this value if the installer does not add the application to Add/Remove Programs. OPAQUE: Specify this value if supplying a registry key or file path does not apply to your installation scenario. This value allows you to specify custom information for the id parameter.
The value to specify for the id parameter depends on the value specified for the scheme parameter: If you specify UNINSTALL_KEY for the scheme parameter, specify the name of the application set in the HKLM\Software\Microsoft\Windows\CurrentVersion registry key. For example, if the registry key is HKLM\Software\Microsoft\Windows\CurrentVersion\MyApp, specify MyApp for the id parameter. If you specify FILEPATH for the scheme parameter, specify the full path to the executable file that installs the assembly as the id parameter. If you specify OPAQUE for the scheme parameter, you can supply any piece of data as the id parameter. The data you specify must be enclosed in quotation marks ("").
The description parameter allows you to specify descriptive text about the application to install. This information is displayed when references are enumerated. | /silent | Suppresses the display of all output. | /u assemblyName | Uninstalls an assembly from the global assembly cache. | /uf assemblyName | Forces a specified assembly to uninstall by removing all references to the assembly. Specifying this option is equivalent to specifying the /u and /f options together. .gif) NoteYou cannot use this option to remove an assembly that was installed using Microsoft Windows Installer. If you attempt this operation, the tool displays an error message. | /ul assemblyListFile | Uninstalls one or more assemblies specified in assemblyListFile from the global assembly cache. | /u[ngen] assemblyName | Uninstalls a specified assembly from the global assembly cache. If the specified assembly has existing reference counts, the tool displays the reference counts and does not remove the assembly from the global assembly cache. Note In the .NET Framework versions 1.0 and 1.1, specifying /ungen causes Gacutil.exe to remove the assembly from the native image cache. This cache stores the native images for assemblies that have been created using the Ngen.exe (Native Image Generator). | /ur assemblyName scheme id description | Uninstalls a reference to a specified assembly from the global assembly cache. To remove a reference to an assembly, you must specify the same scheme, id, and description parameters that were specified with the /i and /r (or /ir) options when the assembly was installed. For a description of the valid values you can specify for these parameters, see the /r option. Specifying this option is equivalent to specifying the /u and /r options together. | /? | Displays command syntax and options for the tool. |
Remarks
This tool provides much of the same functionality for viewing the cache as the Windows Shell Extension (Shfusion.dll), but is more usable from build scripts, makefiles, and batch files. | Note |
|---|
You must have administrator privileges to use Gacutil.exe. |
Specifically, Gacutil.exe allows you to install assemblies into the cache, remove them from the cache, and list the contents of the cache. Gacutil.exe provides options that support reference counting similar to the reference counting scheme supported by Windows Installer. You can use Gacutil.exe to install two applications that install the same assembly; the tool keeps track of the number of references to the assembly. As a result, the assembly will remain on the computer until both applications are uninstalled. If you are using Gacutil.exe for actual product installations, use the options that support reference counting. Use the /i and /r options together to install an assembly and add a reference to count it. Use the /u and /r options together to remove a reference count for an assembly. Be aware that using the /i and /u options alone does not support reference counting. These options are appropriate for use during product development but not for actual product installations. Use the /il or /ul options to install or uninstall a list of assemblies stored in an ANSI text file. The contents of the text file must be formatted correctly. To use a text file to install assemblies, specify the path to each assembly on a separate line in the file. The following example demonstrates the contents of a file containing assemblies to install.
myAssembly1.dll
myAssembly2.dll
myAssembly3.dll
To use a text file to uninstall assemblies, specify the fully qualified assembly name for each assembly on a separate line in the file. The following example demonstrates the contents of a file containing assemblies to uninstall.
myAssembly1,Version=1.1.0.0,Culture=en,PublicKeyToken=874e23ab874e23ab
myAssembly2,Version=1.1.0.0,Culture=en,PublicKeyToken=874e23ab874e23ab
myAssembly3,Version=1.1.0.0,Culture=en,PublicKeyToken=874e23ab874e23ab
Examples
The following command installs the assembly mydll.dll into the global assembly cache.
The following command removes the assembly hello from the global assembly cache as long as no reference counts exist for the assembly.
Note that the previous command might remove more than one assembly from the assembly cache because the assembly name is not fully specified. For example, if both version 1.0.0.0 and 3.2.2.1 of hello are installed in the cache, the command gacutil /u hello removes both of the assemblies. Use the following example to avoid removing more than one assembly. This command removes only the hello assembly that matches the fully specified version number, culture, and public key.
gacutil /u hello, Version=1.0.0.1, Culture="de",PublicKeyToken=45e343aae32233ca
The following command installs the assemblies specified in the file assemblyList.txt into the global assembly cache. gacutil /il assemblyList.txt The following command removes the assemblies specified in the file assemblyList.txt from the global assembly cache. gacutil /ul assemblyList.txt The following command installs myDll.dll into the global assembly cache and adds a reference to count it. The assembly myDll.dll is used by the application MyApp. The UNINSTALL_KEY MyApp parameter specifies the registry key that adds MyApp to Add/Remove Programs in Windows. The description parameter is specified as My Application Description.
gacutil /i /r myDll.dll UNINSTALL_KEY MyApp "My Application Description"
The following command installs myDll.dll into the global assembly cache and adds a reference to count it. The scheme parameter, FILEPATH, and the id parameter, c:\applications\myApp\myApp.exe, specify the path to the application that is installing myDll.dll. The description parameter is specified as MyApp. gacutil /i /r myDll.dll FILEPATH c:\applications\myApp\myApp.exe MyApp The following command installs myDll.dll into the global assembly cache and adds a reference to count it. The scheme parameter, OPAQUE, allows you to customize the id and description parameters.
gacutil /i /r mydll.dll OPAQUE "Insert custom application details here" "Insert Custom description information here"
The following command removes the reference to myDll.dll by the application myApp. If this is the last reference to the assembly, it will also remove the assembly from the global assembly cache. gacutil /u /r myDll.dll FILEPATH c:\applications\myApp\myApp.exe MyApp The following command lists the contents of the global assembly cache.
See Also
ReferenceConceptsOther Resources
Change History
Date | History | Reason |
|---|
April 2011
| Added information about using the Visual Studio and Windows SDK Command Prompts. |
Information enhancement.
|
|
.NET Framework 4 Gacutil.exe (Herramienta Caché global de ensamblados) Esta herramienta permite ver y manipular el contenido de las memorias caché global de ensamblados y caché de descarga. Esta herramienta se instala automáticamente con Visual Studio y con el SDK de Windows. Para ejecutar la herramienta, se recomienda usar el símbolo del sistema de Visual Studio o del SDK de Windows (shell de CMD). Estas utilidades permiten ejecutar la herramienta fácilmente, sin navegar a la carpeta de instalación. Para obtener más información, vea Símbolos del sistema del SDK de Windows y Visual Studio. Si tiene instalado Visual Studio en el equipo: en la barra de tareas, haga clic en Start, All Programs, Visual Studio y Visual Studio Tools y, a continuación, haga clic en Visual Studio Command Prompt. O bien Si tiene el SDK de Windows instalado en el equipo: en la barra de tareas, haga clic en Start, All Programs, haga clic en la carpeta del SDK de Windows y, a continuación, haga clic en Command Prompt (o CMD Shell). En el símbolo del sistema, escriba:
gacutil [options] [assemblyName | assemblyPath | assemblyListFile]
Parámetros
Argumento | Descripción |
|---|
assemblyName | Nombre de un ensamblado. Puede proporcionar un nombre de ensamblado parcialmente especificado, como myAssembly, o un nombre de ensamblado completo, como myAssembly, Version=2.0.0.0, Culture=neutral, PublicKeyToken=0038abc9deabfle5. | assemblyPath | Nombre de un archivo que contiene un manifiesto del ensamblado. | assemblyListFile | Ruta de acceso a un archivo de texto ANSI donde se enumeran los ensamblados que se van a instalar o desinstalar. Si desea utilizar un archivo de texto para instalar ensamblados, especifique la ruta de acceso de cada ensamblado en una línea independiente en el archivo. La herramienta interpreta las rutas de acceso relativas con respecto a la ubicación de assemblyListFile. Si desea utilizar un archivo de texto para desinstalar ensamblados, especifique el nombre completo de cada ensamblado en una línea independiente en el archivo. Puede ver algunos ejemplos del contenido de assemblyListFile más adelante en este tema. |
Opción | Descripción |
|---|
/cdl | Elimina el contenido de la caché de descarga. | /f | Especifique esta opción con las opciones /i o /il para exigir que un ensamblado vuelva a instalarse. Si ya existe un ensamblado con el mismo nombre en la caché global de ensamblados, la herramienta sobrescribe dicho ensamblado. | /h[elp] | Muestra la sintaxis de comandos y opciones para la herramienta. | /i assemblyPath | Instala un ensamblado en la caché global de ensamblados. | /if rutaEnsamblado | Instala un ensamblado en la caché global de ensamblados. Si ya existe un ensamblado con el mismo nombre en la caché global de ensamblados, la herramienta sobrescribe dicho ensamblado. Especificar esta opción equivale a especificar las opciones /i y /f juntas. | /il assemblyListFile | Instala uno o varios ensamblados especificados en assemblyListFile en la caché global de ensamblados. | /ir rutaEnsamblado scheme id description | Instala un ensamblado en la caché global de ensamblados y agrega una referencia para enumerar el ensamblado. Debe especificar los parámetros assemblyPath, scheme, id,y description con esta opción. Para obtener una descripción de los valores válidos para especificar en estos parámetros, vea la opción /r. Especificar esta opción equivale a especificar las opciones /i y /r juntas. | /l [assemblyName] | Enumera el contenido de la caché global de ensamblados. Si se especifica el parámetro assemblyName, la herramienta sólo enumera los ensamblados que coinciden con dicho nombre. | /ldl | Enumera el contenido de la caché de archivos descargados. | /lr [assemblyName] | Enumera todos los ensamblados y sus contadores de referencia correspondientes. Si se especifica el parámetro assemblyName, la herramienta sólo enumera los ensamblados que coinciden con dicho nombre y sus recuentos de referencias correspondientes. | /nologo | Suprime la presentación de la portada de inicio de Microsoft. | /r [assemblyName | assemblyPath] scheme id description | Especifica una referencia de seguimiento a un ensamblado o a varios ensamblados que se vayan a instalar o desinstalar. Especifique esta opción con las opciones /i, /il, /u o /ul. Para instalar un ensamblado, especifique los parámetros assemblyPath, scheme, id,y description con esta opción. Para desinstalar un ensamblado, especifique los parámetros assemblyName, scheme, id,y description. Si desea quitar una referencia a un ensamblado, debe especificar los mismos parámetros scheme, id y description que los que se especificaron con las opciones /i y /r (o /ir) al instalar el ensamblado. A la hora de desinstalar un ensamblado, conviene saber que la herramienta también quita el ensamblado de la caché global de ensamblados si se trata de la última referencia que se va a quitar y si Windows Installer no tiene referencias pendientes al ensamblado. El parámetro scheme especifica el tipo de esquema de instalación. Puede especificar uno de los siguientes valores: UNINSTALL_KEY: especifique este valor si el instalador agrega la aplicación a Agregar o quitar programas en Microsoft Windows. Las aplicaciones se agregan por sí mismas a Agregar o quitar programas ya que agregan una clave del Registro a HKLM\Software\Microsoft\Windows\CurrentVersion. FILEPATH: especifique este valor si el instalador no agrega la aplicación a Agregar o quitar programas. OPAQUE: especifique este valor si el suministro de una clave del Registro o de una ruta de acceso de archivo no son opciones que puedan aplicarse a su escenario de instalación. Este valor permite especificar información personalizada para el parámetro id.
El valor que hay que especificar para el parámetro id depende del valor especificado para el parámetro scheme: Si especifica UNINSTALL_KEY para el parámetro scheme, especifique el nombre de la aplicación establecida en la clave del Registro de HKLM\Software\Microsoft\Windows\CurrentVersion. Por ejemplo, si la clave del Registro es HKLM\Software\Microsoft\Windows\CurrentVersion\MyApp, especifique MyApp para el parámetro id. Si especifica FILEPATH para el parámetro scheme, especifique la ruta de acceso completa al archivo ejecutable que instala el ensamblado como parámetro id. Si especifica OPAQUE para el parámetro scheme, puede suministrar cualquier dato como parámetro id. Los datos que especifique deben ir entre comillas ("").
El parámetro description permite especificar texto descriptivo acerca de la aplicación que se va a instalar. Esta información se muestra cuando se enumeran las referencias. | /silent | Suprime la presentación de todos los resultados. | /u nombreEnsamblado | Desinstala un ensamblado de la caché global de ensamblados. | /uf nombreEnsamblado | Fuerza la desinstalación de un ensamblado específico mediante la eliminación de todas las referencias a éste. Especificar esta opción equivale a especificar las opciones /u y /f juntas. Nota No se puede utilizar esta opción para quitar un ensamblado instalado con Microsoft Windows Installer. Si intenta realizar esta operación, la herramienta muestra un mensaje de error. | /ul assemblyListFile | Desinstala uno o varios ensamblados especificados en assemblyListFile de la caché global de ensamblados. | /u[ngen] assemblyName | Desinstala el ensamblado especificado de la caché global de ensamblados. Si el ensamblado especificado tiene contadores de referencia, la herramienta muestra dichos contadores y no quita el ensamblado de la caché global de ensamblados. Nota En .NET Framework versiones 1.0 y 1.1, si se especifica /ungen, se logra que Gacutil.exe quite el ensamblado de la caché de imágenes nativas. Esta caché almacena las imágenes nativas de los ensamblados creados utilizando Ngen.exe (Generador de imágenes nativas). | /ur nombreEnsamblado scheme id description | Desinstala una referencia a un ensamblado especificado de la caché global de ensamblados. Si desea quitar una referencia a un ensamblado, debe especificar los mismos parámetros scheme, id y description que los que se especificaron con las opciones /i y /r (o /ir) al instalar el ensamblado. Para obtener una descripción de los valores válidos para especificar en estos parámetros, vea la opción /r. Especificar esta opción equivale a especificar las opciones /u y /r juntas. | /? | Muestra la sintaxis de comandos y opciones para la herramienta. |
Comentarios
Esta herramienta proporciona prácticamente la misma funcionalidad que la extensión de la shell de Windows (Shfusion.dll) para ver la memoria caché, pero es preferible utilizarla en scripts de compilación, archivos MAKE y archivos de proceso por lotes. | Nota |
|---|
Debe tener privilegios de administrador para poder utilizar Gacutil.exe. |
Específicamente, Gacutil.exe permite instalar y quitar ensamblados de la caché, así como enumerar el contenido de la misma. Gacutil.exe proporciona opciones que admiten el recuento de referencias, que es parecido al esquema de recuento de referencias compatible con Windows Installer. Puede utilizar Gacutil.exe para instalar dos aplicaciones que instalen el mismo ensamblado; la herramienta realiza un seguimiento del número de referencias al ensamblado. Como consecuencia, el ensamblado permanecerá en el equipo hasta que se desinstalen ambas aplicaciones. Si utiliza Gacutil.exe para realizar instalaciones de productos propiamente dichas, utilice las opciones que admiten el recuento de referencias. Utilice las opciones /i y /r de forma conjunta para instalar un ensamblado y agregar una referencia al mismo a fin de enumerarlo. Utilice las opciones /u y /r de forma conjunta para quitar un contador de referencias para un ensamblado. Tenga en cuenta que el uso de las opciones /i y /u por separado no es compatible con el recuento de referencias. Es adecuado utilizar estas opciones durante el desarrollo del producto, pero no para realizar instalaciones de productos propiamente dichas. Utilice las opciones /il o /ul para instalar o desinstalar una lista de ensamblados almacenados en un archivo de texto ANSI. El contenido del archivo de texto debe tener el formato correcto. Si desea utilizar un archivo de texto para instalar ensamblados, especifique la ruta de acceso de cada ensamblado en una línea independiente en el archivo. En el siguiente ejemplo se muestra el contenido de un archivo que contiene los ensamblados que se van a instalar.
myAssembly1.dll
myAssembly2.dll
myAssembly3.dll
Si desea utilizar un archivo de texto para desinstalar ensamblados, especifique el nombre completo de cada ensamblado en una línea independiente en el archivo. En el siguiente ejemplo se muestra el contenido de un archivo que contiene los ensamblados que se van a desinstalar.
myAssembly1,Version=1.1.0.0,Culture=en,PublicKeyToken=874e23ab874e23ab
myAssembly2,Version=1.1.0.0,Culture=en,PublicKeyToken=874e23ab874e23ab
myAssembly3,Version=1.1.0.0,Culture=en,PublicKeyToken=874e23ab874e23ab
Ejemplos
El comando siguiente instala el ensamblado mydll.dll en la caché global de ensamblados.
El comando siguiente quita el ensamblado hello de la caché global de ensamblados, ya que no existen contadores de referencia para el ensamblado.
Observe que el comando anterior puede quitar más de un ensamblado de la caché porque no se ha especificado completamente el nombre del ensamblado. Por ejemplo, si se han instalado en la caché las versiones 1.0.0.0 y 3.2.2.1 de hello, el comando gacutil /u hello quita los dos ensamblados. Utilice el ejemplo siguiente para no quitar más de un ensamblado. Este comando quita sólo el ensamblado hello cuyos número de versión, referencia cultural y clave pública se han especificado completamente.
gacutil /u hello, Version=1.0.0.1, Culture="de",PublicKeyToken=45e343aae32233ca
El comando siguiente instala los ensamblados especificados en el archivo assemblyList.txt en la caché global de ensamblados. gacutil /il assemblyList.txt El comando siguiente quita los ensamblados especificados en el archivo assemblyList.txt de la caché global de ensamblados. gacutil /ul assemblyList.txt El comando siguiente instala myDll.dll en la caché global de ensamblados y agrega una referencia para enumerarlo. La aplicación MyApp utiliza el ensamblado myDll.dll. El parámetro UNINSTALL_KEY MyApp especifica la clave del Registro que agrega MyApp a Agregar o quitar programas en Windows. El parámetro description se especifica de la forma My Application Description.
gacutil /i /r myDll.dll UNINSTALL_KEY MyApp "My Application Description"
El comando siguiente instala myDll.dll en la caché global de ensamblados y agrega una referencia para enumerarlo. El parámetro scheme, FILEPATH, y el parámetro id, c:\applications\myApp\myApp.exe, especifican la ruta de acceso a la aplicación que va a instalar myDll.dll. El parámetro description se especifica de la forma MyApp gacutil /i /r myDll.dll FILEPATH c:\applications\myApp\myApp.exe MyApp El comando siguiente instala myDll.dll en la caché global de ensamblados y agrega una referencia para enumerarlo. El parámetro scheme, OPAQUE, permite personalizar los parámetros id y description.
gacutil /i /r mydll.dll OPAQUE "Insert custom application details here" "Insert Custom description information here"
El comando siguiente quita la referencia a myDll.dll por medio de la aplicación myApp. Si se trata de la última referencia al ensamblado, también quitará el ensamblado de la caché global de ensamblados. gacutil /u /r myDll.dll FILEPATH c:\applications\myApp\myApp.exe MyApp El comando siguiente enumera el contenido de la caché global de ensamblados.
Vea también
ReferenciaConceptosOtros recursos
Historial de cambios
Fecha | Historial | Motivo |
|---|
1 de abril de 2011
| Se agregó información sobre el uso de los símbolos del sistema de Visual Studio y del SDK de Windows. |
Mejora de la información.
|
|