Marshal.ReleaseComObject(Object) Marshal.ReleaseComObject(Object) Marshal.ReleaseComObject(Object) Marshal.ReleaseComObject(Object) Method

Definizione

Decrementa il conteggio dei riferimenti del Runtime Callable Wrapper (RCW) associato all'oggetto COM specificato.Decrements the reference count of the Runtime Callable Wrapper (RCW) associated with the specified COM object.

public:
 static int ReleaseComObject(System::Object ^ o);
[System.Security.SecurityCritical]
public static int ReleaseComObject (object o);
static member ReleaseComObject : obj -> int
Public Shared Function ReleaseComObject (o As Object) As Integer

Parametri

o
Object Object Object Object

Oggetto COM da rilasciare.The COM object to release.

Restituisce

Nuovo valore del conteggio dei riferimenti dell'RCW associato a o.The new value of the reference count of the RCW associated with o. Questo valore in genere è zero poiché RCW conserva solo un riferimento all'oggetto COM incluso indipendentemente dal numero dei client gestiti che lo chiamano.This value is typically zero since the RCW keeps just one reference to the wrapped COM object regardless of the number of managed clients calling it.

Eccezioni

o non è un oggetto COM valido.o is not a valid COM object.

Commenti

Questo metodo viene utilizzato per controllare in modo esplicito la durata di un oggetto COM utilizzato dal codice gestito.This method is used to explicitly control the lifetime of a COM object used from managed code. È consigliabile utilizzare questo metodo per liberare l'oggetto COM sottostante che include i riferimenti alle risorse in modo tempestivo o quando gli oggetti devono essere liberati in un ordine specifico.You should use this method to free the underlying COM object that holds references to resources in a timely manner or when objects must be freed in a specific order.

Ogni volta che un puntatore a un'interfaccia COM entra nel Common Language Runtime (CLR), ne viene eseguito il wrapper in un RCW.Every time a COM interface pointer enters the common language runtime (CLR), it is wrapped in an RCW.

L'RCW dispone di un conteggio dei riferimenti incrementato ogni volta che viene eseguito il mapping di un puntatore a un'interfaccia COM.The RCW has a reference count that is incremented every time a COM interface pointer is mapped to it. Il metodo ReleaseComObject decrementa il conteggio dei riferimenti di un RCW.The ReleaseComObject method decrements the reference count of an RCW. Quando il conteggio dei riferimenti raggiunge zero, il runtime rilascia tutti i relativi riferimenti nell'oggetto COM non gestito e genera un'eccezione System.NullReferenceException se si tenta di utilizzare ulteriormente l'oggetto.When the reference count reaches zero, the runtime releases all its references on the unmanaged COM object, and throws a System.NullReferenceException if you attempt to use the object further. Se la stessa interfaccia COM viene passata più di una volta dal codice non gestito a quello gestito, il conteggio dei riferimenti sul wrapper viene incrementato ogni volta e la chiamata a ReleaseComObject restituisce il numero di riferimenti rimanenti.If the same COM interface is passed more than one time from unmanaged to managed code, the reference count on the wrapper is incremented every time, and calling ReleaseComObject returns the number of remaining references.

Questo metodo consente di forzare una versione di conteggio riferimenti RCW in modo che si verifichi esattamente quando lo si desidera.This method enables you to force an RCW reference count release so that it occurs precisely when you want it to. Tuttavia, l'uso improprio di ReleaseComObject può causare un errore dell'applicazione o potrebbe causare una violazione di accesso.However, improper use of ReleaseComObject may cause your application to fail, or may cause an access violation.

Si consideri uno scenario in cui il codice gestito in un dominio dell'applicazione mantiene un RCW che rappresenta un componente COM.Consider a scenario in which managed code in an application domain is holding onto an RCW that represents a COM component. Se si chiama il metodo ReleaseComObject sull'RCW, il codice gestito non sarà in grado di accedere all'RCW e genererà un'eccezione InvalidComObjectException.If you call the ReleaseComObject method on the RCW, the managed code will be unable to access the RCW and will raise an InvalidComObjectException exception.

È possibile che si verifichi un errore più grave se viene eseguita una chiamata al RCW quando viene rilasciato l'RCW.A more serious error may occur if a call to the RCW is executing when the RCW is released. In questo caso, è probabile che il thread che effettua la chiamata provochi una violazione di accesso.In this case, there is a good chance that the thread making the call will cause an access violation. Tuttavia, è possibile che la memoria del processo venga danneggiata e che il processo continui a funzionare fino a quando non si verificano errori per motivi difficili da sottomettere a debug.However, process memory may become corrupted, and the process may continue to run until it fails for reasons that are very difficult to debug.

Questo rischio è composto quando il componente COM utilizzato è un singleton, per il motivo seguente: CLR attiva i componenti COM chiamando la funzione COM CoCreateInstance , che restituisce lo stesso puntatore di interfaccia ogni volta che viene chiamata per i componenti COM singleton.This risk is compounded when the COM component that is being used is a singleton, for the following reason: The CLR activates COM components by calling the COM CoCreateInstance function, which returns the same interface pointer every time it is called for singleton COM components. Pertanto, parti separate e indipendenti del codice gestito in un dominio applicazione possono utilizzare lo stesso RCW per un componente COM singleton e se uno chiama il metodo ReleaseComObject sul componente COM, l'altro verrà danneggiato.Thus, separate and independent pieces of managed code in an application domain can be using the same RCW for a singleton COM component, and if either one calls the ReleaseComObject method on the COM component, the other will be broken.

Pertanto, utilizzare il ReleaseComObject solo se è assolutamente necessario.Therefore, use the ReleaseComObject only if it is absolutely required. Se si vuole chiamare questo metodo per garantire che un componente COM venga rilasciato a un determinato momento, provare a usare il metodo FinalReleaseComObject.If you want to call this method to ensure that a COM component is released at a determined time, consider using the FinalReleaseComObject method instead. FinalReleaseComObject rilascerà il componente COM sottostante indipendentemente dal numero di volte in cui è stato immesso nuovamente in CLR.FinalReleaseComObject will release the underlying COM component regardless of how many times it has re-entered the CLR. Il conteggio dei riferimenti interni dell'RCW viene incrementato di uno ogni volta che il componente COM immette di nuovo CLR.The internal reference count of the RCW is incremented by one every time the COM component re-enters the CLR. Pertanto, è possibile chiamare il metodo ReleaseComObject in un ciclo fino a quando il valore restituito è zero.Therefore, you could call the ReleaseComObject method in a loop until the value returned is zero. In questo modo si ottiene lo stesso risultato del metodo FinalReleaseComObject.This achieves the same result as the FinalReleaseComObject method.

Sicurezza

SecurityCriticalAttribute
richiede l'attendibilità totale per il chiamante immediato.requires full trust for the immediate caller. Questo membro non può essere utilizzato da codice parzialmente attendibile o trasparente.This member cannot be used by partially trusted or transparent code.

Si applica a

Vedi anche