Arquivos de configuração de aplicativo

Um arquivo de configuração de aplicativo é um arquivo XML usado para controlar a associação de assembly. Ele pode redirecionar um aplicativo do uso de uma versão de um assembly lado a lado para outra versão do mesmo assembly. Isso é chamado de configuração por aplicativo. Um arquivo de configuração de aplicativo se aplica apenas a um manifesto de aplicativo específico e assemblies dependentes. Componentes isolados compilados com um manifesto de ISOLATIONAWARE_MANIFEST_RESOURCE_ID inserido exigem um arquivo de configuração de aplicativo separado. Os manifestos gerenciados com CreateActCtx exigem um arquivo de configuração de aplicativo separado.

O redirecionamento especificado por um arquivo de configuração de aplicativo pode substituir as versões de assembly especificadas por manifestos de aplicativo e arquivos de configuração do editor. Por exemplo, se um arquivo de configuração do editor especificar que todas as referências a um assembly serão redirecionadas da versão 1.0.0.0 para 1.1.0.0, um arquivo de configuração de aplicativo poderá ser usado para redirecionar um aplicativo específico para usar a versão 1.0.0.0. Um arquivo de configuração de aplicativo se aplica somente ao manifesto do aplicativo especificado e aos assemblies dependentes.

Para obter uma listagem completa do esquema XML, consulte Esquema de arquivo de configuração de aplicativo.

Os arquivos de configuração do aplicativo têm os elementos e atributos mostrados na tabela a seguir.

Elemento	Atributos	Obrigatório
configuração		Sim
windows		Yes
publisherPolicy		Sim
	apply	Sim
Runtime		Não
assemblyBinding		Sim
Sondagem		Não
	Privatepath	Sim
Dependência		Não
dependentAssembly		Sim
assemblyIdentity		Sim
	tipo	Sim
	name	Sim
	linguagem	Não
	Processorarchitecture	Sim
	version	Sim
	publicKeyToken	Não
bindingRedirect		Sim
	oldVersion	Sim
	newVersion	Sim

Localização do arquivo

Os arquivos de configuração do aplicativo devem ser instalados no mesmo local que o manifesto do aplicativo.

Sintaxe de nome de arquivo

O nome de um arquivo de configuração de aplicativo é o nome do executável do aplicativo seguido por .config.

Por exemplo, um arquivo de configuração de aplicativo que se refere a Example.exe ou Example.dll usaria a sintaxe de nome de arquivo mostrada no exemplo a seguir. Você pode omitir o campo da <ID> do recurso se estiver instalando o arquivo de configuração como um arquivo separado ou se a ID do recurso for 1.

example.exe.<ID do> recurso.config

example.dll.<ID do> recurso.config

Elementos

Os nomes de elementos e atributos diferenciam maiúsculas de minúsculas. Os valores de elementos e atributos não diferenciam maiúsculas de minúsculas, exceto pelo valor do atributo de tipo.

configuração

Um elemento de contêiner para os elementos windows e runtime de um arquivo de configuração de aplicativo. Obrigatórios.

windows

Inclui as partes do arquivo de configuração de aplicativo que se aplicam ao redirecionamento de assemblies Win32.

Observação

O autor de um aplicativo não deve incluir um arquivo de configuração com um subelemento do Windows como parte de seu aplicativo. Isso poderá ser permitido se a única finalidade do arquivo de configuração for habilitar a funcionalidade privatePath de um elemento de investigação . O elemento de investigação não está disponível em sistemas anteriores ao Windows Server 2008 R2 e Windows 7.

publisherPolicy

Especifica se a política do editor deve ser aplicada.

Esse elemento tem os atributos mostrados na tabela a seguir.

Atributo	Descrição
apply	Um valor de "sim" aplica a política do editor. Essa é a configuração padrão. O valor "não" não aplica a política do editor.

runtime

Inclui as partes do arquivo de configuração do aplicativo que se aplicam ao redirecionamento de assemblies .Net.

assemblyBinding

Inclui as informações de redirecionamento para o aplicativo e o assembly afetado por esse arquivo de configuração de aplicativo. O primeiro subelemento de assemblyBinding deve ser uma assemblyIdentity que identifique o aplicativo.

A partir do Windows Server 2008 R2 e do Windows 7, um elemento assemblyBinding pode incluir um subelemento de investigação .

Sondagem

Um subelemento opcional de um elemento assemblyBinding que estende a pesquisa de assemblies para diretórios adicionais. Os diretórios adicionais não precisam ser subdiretórios do diretório do assembly.

Observação

Esse elemento não está disponível em sistemas anteriores ao Windows Server 2008 R2 e Windows 7 e só pode ser usado em um elemento windows .

Esse elemento tem os atributos mostrados na tabela a seguir.

Atributo	Descrição
Privatepath	Especifica os caminhos relativos de subdiretórios do diretório base do aplicativo que podem conter assemblies. No máximo nove caminhos de subdiretório podem ser especificados. Delimita cada caminho de subdiretório com um ponto e vírgula.

Você pode usar o especificador especial de pontos duplos em um caminho para denotar o diretório pai do diretório atual. Não mais do que dois níveis acima do diretório atual podem ser especificados usando ponto duplo. Não use três ponto. Por exemplo, um aplicativo que usa o seguinte elemento de investigação verifica diretórios adicionais para um assembly.

<probing privatePath="bin;..\bin2\subbin;bin3"/>

dependência

Um elemento de contêiner para pelo menos um dependentAssembly. Cada dependentAssembly pode estar dentro de exatamente uma dependência. Esse elemento não tem atributos. Opcional.

dependentAssembly

O primeiro subelemento deve ser um elemento assemblyIdentity que identifica o assembly lado a lado que está sendo redirecionado pelo arquivo de configuração do aplicativo. Um dependentAssembly não tem atributos.

assemblyIdentity

Como o primeiro subelemento de um elemento assemblyBinding , assemblyIdentity descreve e identifica exclusivamente um aplicativo. O arquivo de configuração do aplicativo redireciona a associação desse aplicativo para assemblies lado a lado. Por exemplo, o assemblyIdentity a seguir indica que o arquivo de configuração do aplicativo afeta a associação do aplicativo mysampleApp a assemblies lado a lado. Os assemblies que estão sendo redirecionados seriam identificados em um dependentAssembly.

<assemblyIdentity processorArchitecture="X86" name="Microsoft.Windows.mysampleApp" type="win32" version="1.0.0.0"/>

Como o primeiro subelemento de um elemento dependentAssembly , assemblyIdentity descreve um assembly lado a lado do qual o aplicativo depende. O arquivo de configuração do aplicativo reconfigura a identidade desse assembly necessário. Por exemplo, o assemblyIdentity e bindingRedirect a seguir reconfigura uma dependência em Microsoft.Windows.SampleAssembly da versão 2.0.0.0 para a versão 2.1.0.0.

<dependency>
      <dependentAssembly>
         <assemblyIdentity type="win32"
          name="Microsoft.Windows.SampleAssembly"
          processorArchitecture="x86"
          publicKeyToken="0000000000000000"/>
         <bindingRedirect oldVersion="2.0.0.0" newVersion="2.1.0.0"/>
      </dependentAssembly>
</dependency>

Observe que cada assemblyIdentity incluído em um dependentAssembly deve corresponder exatamente à assemblyIdentity no manifesto do assembly.

O elemento assemblyIdentity tem os seguintes atributos. Ele não tem subelementos.

Atributo	Descrição
tipo	O valor deve ser win32 (maiúsculas e minúsculas). Obrigatórios.
name	O atributo name identifica o aplicativo que está sendo afetado pelo arquivo de configuração do aplicativo ou pelo assembly que está sendo redirecionado. Use o seguinte formato para o nome: Organization.Division.Name. Obrigatórios. Por exemplo: Microsoft.Windows.MysampleApp ou Microsoft.Windows.MysampleAsm.
linguagem	Identifica o idioma. Opcional. Para um assemblyIdentity que se refere a um assembly, se o assembly for específico do idioma, especifique o código de linguagem DHTML. Se o assembly for para uso mundial (idioma neutro) defina o valor como "*".
Processorarchitecture	Especifica o processador que executa o aplicativo.
version	Especifica a versão do aplicativo ou assembly. Use a sintaxe de versão de quatro partes: mmmm.nnnn.oooo.pppp. Obrigatórios.
publicKeyToken	Para uma assemblyIdentity que se refere a um assembly, uma cadeia de caracteres hexadecimal de 16 caracteres que representa os últimos 8 bytes do hash SHA-1 da chave pública sob a qual o assembly é assinado. A chave pública usada para assinar o catálogo deve ter 2.048 bits ou mais. Necessário para todos os assemblies lado a lado compartilhados.

bindingRedirect

O elemento bindingRedirect contém informações de redirecionamento para a associação do assembly. Cada bindingRedirect deve ser incluído em exatamente um dependentAssembly. A sintaxe de versão de quatro partes da nova versão e a versão antiga devem especificar as mesmas versões principais e secundárias.

Esse elemento tem os atributos mostrados na tabela a seguir.

Atributo	Descrição
oldVersion	Especifica a versão do assembly que está sendo substituída e redirecionada. Use a sintaxe de versão de quatro partes nnnnn.nnnnn.nnnnn.nnnnn.nnnnn. Especifique um intervalo de versões por um traço sem espaços. Por exemplo, 2.14.3.0 ou 2.14.3.0 2.16.0.0. Obrigatórios.
newVersion	Especifica a versão do assembly de substituição. Use a sintaxe de versão de quatro partes nnnnn.nnnnn.nnnnn.nnnnn.

Comentários

Os arquivos de configuração do aplicativo não especificam arquivos.

Exemplo

<bindingRedirect oldVersion="1.0.0.0" newVersion="1.0.10.0"/>
<bindingRedirect oldVersion="1.0.50.2011-1.0.60.65535" newVersion="1.0.70.0"/>