Método Marshal.GetActiveObject (String)

Artigo
04/19/2018

Dica

The .NET API Reference documentation has a new home. Visit the .NET API Browser on docs.microsoft.com to see the new experience.

Obtém uma instância em execução do objeto especificado do ROT (tabela de objetos em execução).

Namespace: System.Runtime.InteropServices
Assembly: mscorlib (em mscorlib.dll)

Sintaxe

[SecurityCriticalAttribute]
public static object GetActiveObject(
    string progID
)

public:
[SecurityCriticalAttribute]
static Object^ GetActiveObject(
    String^ progID
)

[<SecurityCriticalAttribute>]
static member GetActiveObject : 
        progID:string -> Object

<SecurityCriticalAttribute>
Public Shared Function GetActiveObject (
    progID As String
) As Object

Parâmetros

progID
Type: System.String

O ProgID (identificador programático) do objeto solicitado.

Valor Retornado

Type: System.Object

O objeto que foi solicitado; caso contrário, null. Você pode converter esse objeto em qualquer interface COM à qual ele dê suporte.

Exceções

Exception	Condition
COMException	O objeto não foi encontrado.

Comentários

GetActiveObjectexpõe o COM GetActiveObject função OLEAUT32. DLL; No entanto, o último esperava um identificador de classe (CLSID) em vez do identificador programático (ProgID) esperados por este método. Para obter uma instância em execução de um objeto COM sem um registrado ProgID, usar invocação de plataforma para definir o COM GetActiveObject função. Para obter uma descrição da plataforma invoke, consulte Consumindo funções de DLL não gerenciadas.

ProgID e CLSID

As chaves na subárvore HKEY_CLASSES_ROOT do registro contêm uma variedade de tipos de subchave. A maioria das subchaves são ProgIDs, que mapeiam uma cadeia de caracteres amigável para um CLSID. Aplicativos geralmente usam essas cadeias de caracteres legível em vez dos CLSIDs numéricos. Geralmente, um componente tem uma versão de ProgID que é mapeado para a versão mais recente do componente que é instalado no sistema.

Aplicativos e componentes principalmente usam ProgIDs para recuperar seus CLSIDs correspondentes.

Exemplos

O exemplo a seguir foi executado em um computador que foi configurado com uma instância em execução do Microsoft Word. Não havia nenhuma instância do Microsoft Excel em execução.

O exemplo chama GetActiveObject duas vezes. A primeira chamada tenta recuperar uma referência a uma instância do Microsoft Word (uma instância do Word.Application objeto). A segunda chamada tenta recuperar uma referência a uma instância do Microsoft Excel (uma instância de um Excel.Application objeto).

O código recupera uma referência a uma instância do Microsoft Word com êxito. No entanto, como o Microsoft Excel não está em execução, a tentativa de recuperar o segundo objeto gera um COMException.

using System;
using System.Runtime.InteropServices;

class MainFunction
{
    static void Main()
        {
        Console.WriteLine("\nSample: C# System.Runtime.InteropServices.Marshal.GetActiveObject.cs\n"); 

        GetObj(1, "Word.Application");
        GetObj(2, "Excel.Application");
        }

    static void GetObj(int i, String progID)
    {
        Object obj = null;

        Console.WriteLine("\n" +i+") Object obj = GetActiveObject(\"" + progID + "\")");
        try
           { obj = Marshal.GetActiveObject(progID); }
        catch (Exception e)
           {
           Write2Console("\n   Failure: obj did not get initialized\n" + 
                         "   Exception = " +e.ToString().Substring(0,43), 0); 
           }

        if (obj != null)
           { Write2Console("\n   Success: obj = " + obj.ToString(), 1 ); }
    }


    static void Write2Console(String s, int color)
        {
        Console.ForegroundColor = color == 1? ConsoleColor.Green : ConsoleColor.Red;
        Console.WriteLine(s); 
        Console.ForegroundColor = ConsoleColor.Gray;
    }
}

/*
Expected Output:

Sample: C# System.Runtime.InteropServices.Marshal.GetActiveObject.cs

1) Object obj = GetActiveObject("Word.Application")

   Success: obj = System.__ComObject

2) Object obj = GetActiveObject("Excel.Application")

   Failure: obj did not get initialized
   Exception = System.Runtime.InteropServices.COMException
*/

Imports System
Imports System.Runtime.InteropServices

Module Module1

    Sub Main()
        Console.WriteLine(vbcrlf + "Sample: VB System.Runtime.InteropServices.Marshal.GetActiveObject.vb" + vbcrlf) 
        GetObj(1, "Word.Application")
        GetObj(2, "Excel.Application")
    End Sub


    Sub GetObj(ByVal i As Integer, ByVal progID As [String])
        Dim obj As [Object] = Nothing

        Console.WriteLine((vbLf & i & ") Object obj = GetActiveObject(""") + progID & """)")
        Try
            obj = Marshal.GetActiveObject(progID)
        Catch e As Exception
            Write2Console((vbLf & "   Failure: obj did not get initialized" & vbLf & "   Exception = ") + e.ToString().Substring(0, 43), 0)
        End Try

        If obj IsNot Nothing Then
            Write2Console(vbLf & "   Success: obj = " & obj.ToString(), 1)
        End If
    End Sub

    Sub Write2Console(ByVal s As [String], ByVal color As Integer)
        Console.ForegroundColor = If(color = 1, ConsoleColor.Green, ConsoleColor.Red)
        Console.WriteLine(s)
        Console.ForegroundColor = ConsoleColor.Gray
    End Sub

End Module

'Expected Output:
'
'Sample: VB System.Runtime.InteropServices.Marshal.GetActiveObject.vb
'
'1) Object obj = GetActiveObject("Word.Application")
'
'   Success: obj = System.__ComObject
'
'2) Object obj = GetActiveObject("Excel.Application")
'
'   Failure: obj did not get initialized
'   Exception = System.Runtime.InteropServices.COMException
'

Segurança

SecurityCriticalAttribute

requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.

Informações de Versão

.NET Framework
Disponível desde 1.1

Confira Também

Classe Marshal
Namespace System.Runtime.InteropServices

Retornar ao início

Compartilhar via