Marshal.ReleaseComObject(Object) Método
Definição
Importante
Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.
Diminui a contagem de referência do RCW (Runtime Callable Wrapper) associado ao objeto COM especificado.
public:
static int ReleaseComObject(System::Object ^ o);
[System.Security.SecurityCritical]
public static int ReleaseComObject (object o);
[System.Runtime.Versioning.SupportedOSPlatform("windows")]
public static int ReleaseComObject (object o);
public static int ReleaseComObject (object o);
[<System.Security.SecurityCritical>]
static member ReleaseComObject : obj -> int
[<System.Runtime.Versioning.SupportedOSPlatform("windows")>]
static member ReleaseComObject : obj -> int
static member ReleaseComObject : obj -> int
Public Shared Function ReleaseComObject (o As Object) As Integer
Parâmetros
- o
- Object
O objeto COM a ser liberado.
Retornos
O novo valor da contagem de referência do RCW associado ao o
. Normalmente, esse valor é zero, pois o RCW mantém apenas uma referência ao objeto COM encapsulado, independentemente do número de clientes gerenciados que estejam chamando-o.
- Atributos
Exceções
O o
não é um objeto COM válido.
o
é null
.
Comentários
Esse método é usado para controlar explicitamente o tempo de vida de um objeto COM usado do código gerenciado. Você deve usar esse método para liberar o objeto COM subjacente que contém referências a recursos em tempo hábil ou quando os objetos devem ser liberados em uma ordem específica.
Sempre que um ponteiro de interface COM entra no CLR (Common Language Runtime), ele é encapsulado em um RCW.
O RCW tem uma contagem de referência que é incrementada sempre que um ponteiro de interface COM é mapeado para ele. O ReleaseComObject método decrementa a contagem de referência de um RCW. Quando a contagem de referência atinge zero, o runtime libera todas as suas referências no objeto COM não gerenciado e lança um System.NullReferenceException se você tentar usar o objeto ainda mais. Se a mesma interface COM for passada mais de uma vez de não gerenciada para o código gerenciado, a contagem de referência no wrapper será incrementada sempre e a chamada ReleaseComObject retornará o número de referências restantes.
Esse método permite que você force uma versão de contagem de referência RCW para que ela ocorra precisamente quando você quiser. No entanto, o uso inadequado pode ReleaseComObject fazer com que seu aplicativo falhe ou possa causar uma violação de acesso.
Considere um cenário no qual o código gerenciado em um domínio de aplicativo está mantendo um RCW que representa um componente COM. Se você chamar o ReleaseComObject método no RCW, o código gerenciado não poderá acessar o RCW e gerará uma exceção InvalidComObjectException .
Um erro mais grave poderá ocorrer se uma chamada para o RCW estiver sendo executada quando o RCW for liberado. Nesse caso, há uma boa chance de que o thread que está fazendo a chamada cause uma violação de acesso. No entanto, a memória do processo pode ficar corrompida e o processo pode continuar a ser executado até que falhe por motivos muito difíceis de depurar.
Esse risco é agravado quando o componente COM que está sendo usado é um singleton, pelo seguinte motivo: o CLR ativa componentes COM chamando a função COM CoCreateInstance , que retorna o mesmo ponteiro de interface sempre que é chamado para componentes COM singleton. Assim, partes separadas e independentes do código gerenciado em um domínio de aplicativo podem estar usando o mesmo RCW para um componente COM singleton e, se uma chamar o ReleaseComObject método no componente COM, a outra será interrompida.
Portanto, use o ReleaseComObject único se for absolutamente necessário. Se você quiser chamar esse método para garantir que um componente COM seja liberado em um momento determinado, considere usar o FinalReleaseComObject método em vez disso. FinalReleaseComObject lançará o componente COM subjacente, independentemente de quantas vezes ele tenha entrado novamente no CLR. A contagem de referência interna do RCW é incrementada por um sempre que o componente COM entra novamente no CLR. Portanto, você pode chamar o ReleaseComObject método em um loop até que o valor retornado seja zero. Isso obtém o mesmo resultado que o FinalReleaseComObject método.