Marshal.ReleaseComObject(Object) Metoda

Definicja

Zmniejsza liczbę odwołań otoki wywoływanych przez środowisko uruchomieniowe (RCW) skojarzonych z określonym obiektem com.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

Parametry

o
Object

Obiekt COM do zwolnienia.The COM object to release.

Zwraca

Nowa wartość liczby odwołań otoki RCW skojarzonej z o.The new value of the reference count of the RCW associated with o. Ta wartość jest zwykle równa zero, ponieważ OTOKa utrzymuje tylko jedno odwołanie do zapakowanego obiektu COM, niezależnie od liczby klientów zarządzanych wywołujących ją.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.

Atrybuty

Wyjątki

o nie jest prawidłowym obiektem COM.o is not a valid COM object.

o jest null.o is null.

Uwagi

Ta metoda służy do jawnej kontroli okresu istnienia obiektu COM używanego z kodu zarządzanego.This method is used to explicitly control the lifetime of a COM object used from managed code. Tej metody należy użyć do zwolnienia bazowego obiektu COM, który przechowuje odwołania do zasobów w odpowiednim czasie lub gdy obiekty muszą być zwolnione w określonej kolejności.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.

Za każdym razem, gdy wskaźnik interfejsu COM przechodzi do środowiska uruchomieniowego języka wspólnego (CLR), jest opakowany w otokę RCW.Every time a COM interface pointer enters the common language runtime (CLR), it is wrapped in an RCW.

Otoka RCW ma licznik odwołań, który jest zwiększany za każdym razem, gdy wskaźnik interfejsu COM jest mapowany na go.The RCW has a reference count that is incremented every time a COM interface pointer is mapped to it. Metoda ReleaseComObject zmniejsza liczbę odwołań otoki RCW.The ReleaseComObject method decrements the reference count of an RCW. Gdy liczba odwołań osiągnie wartość zero, środowisko uruchomieniowe zwolni wszystkie odwołania do niezarządzanego obiektu COM i zgłosi System.NullReferenceException, jeśli spróbujesz użyć obiektu.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. Jeśli ten sam interfejs COM przeszedł więcej niż jeden raz z niezarządzanego do kodu zarządzanego, liczba odwołań dla otoki jest zwiększana za każdym razem, a wywołanie ReleaseComObject zwraca liczbę pozostałych odwołań.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.

Ta metoda pozwala wymusić wymuszanie wersji referencyjnej OTOKi, tak aby była dokładnie wykonywana, gdy chcesz.This method enables you to force an RCW reference count release so that it occurs precisely when you want it to. Jednak nieprawidłowe użycie ReleaseComObject może spowodować niepowodzenie aplikacji lub spowodować naruszenie zasad dostępu.However, improper use of ReleaseComObject may cause your application to fail, or may cause an access violation.

Rozważmy scenariusz, w którym kod zarządzany w domenie aplikacji znajduje się na otoki RCW, która reprezentuje składnik COM.Consider a scenario in which managed code in an application domain is holding onto an RCW that represents a COM component. Jeśli wywołasz metodę ReleaseComObject w otoki RCW, kod zarządzany nie będzie w stanie uzyskać dostępu do otoki RCW i wywoła wyjątek 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.

Może wystąpić bardziej poważny błąd, jeśli wywołanie OTOKi jest wykonywane po wydaniu OTOKi.A more serious error may occur if a call to the RCW is executing when the RCW is released. W takim przypadku istnieje dobry szansa, że wątek wywołujący wywołanie spowoduje naruszenie zasad dostępu.In this case, there is a good chance that the thread making the call will cause an access violation. Jednak pamięć procesu może ulec uszkodzeniu, a proces może nadal działać do momentu, gdy nie powiedzie się to z przyczyn, które są bardzo trudne do debugowania.However, process memory may become corrupted, and the process may continue to run until it fails for reasons that are very difficult to debug.

To ryzyko jest złożone, gdy używany składnik COM jest pojedyncza, z następującej przyczyny: środowisko CLR aktywuje składniki COM przez wywołanie funkcji CoCreateInstance języka com, która zwraca ten sam wskaźnik interfejsu za każdym razem, gdy jest wywoływana dla pojedyncze składniki COM.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. W ten sposób oddzielne i niezależne fragmenty kodu zarządzanego w domenie aplikacji mogą używać tej samej OTOKi dla pojedynczego składnika COM, a jeśli jeden wywołuje metodę ReleaseComObject w składniku COM, drugi zostanie przerwany.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.

W związku z tym należy używać ReleaseComObject tylko wtedy, gdy jest to absolutnie wymagane.Therefore, use the ReleaseComObject only if it is absolutely required. Jeśli chcesz wywołać tę metodę, aby upewnić się, że składnik modelu COM jest wydawany w określonym czasie, rozważ użycie metody 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 zwolni bazowego składnika COM bez względu na to, ile razy ponownie wprowadzono środowisko CLR.FinalReleaseComObject will release the underlying COM component regardless of how many times it has re-entered the CLR. Wewnętrzna liczba odwołań dla otoki RCW jest zwiększana o jeden po każdym ponownym wprowadzeniu środowiska CLR przez składnik COM.The internal reference count of the RCW is incremented by one every time the COM component re-enters the CLR. W związku z tym, można wywołać metodę ReleaseComObject w pętli do momentu zwrócenia wartości równej zero.Therefore, you could call the ReleaseComObject method in a loop until the value returned is zero. Osiąga to ten sam wynik, co Metoda FinalReleaseComObject.This achieves the same result as the FinalReleaseComObject method.

Zabezpieczenia

SecurityCriticalAttribute
Wymaga pełnego zaufania do bezpośredniego obiektu wywołującego.requires full trust for the immediate caller. Ten element członkowski nie może być używany przez częściowo zaufany lub przejrzysty kod.This member cannot be used by partially trusted or transparent code.

Dotyczy

Zobacz też