Classe COMException

 

Observação

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

A exceção é lançada quando um HRESULT não reconhecido retorna de uma chamada de método COM.

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

Hierarquia de Herança

System.Object
  System.Exception
    System.SystemException
      System.Runtime.InteropServices.ExternalException
        System.Runtime.InteropServices.COMException
          System.DirectoryServices.DirectoryServicesCOMException

Sintaxe

[SerializableAttribute]
[ComVisibleAttribute(true)]
public class COMException : ExternalException

[SerializableAttribute]
[ComVisibleAttribute(true)]
public ref class COMException : ExternalException

[<SerializableAttribute>]
[<ComVisibleAttribute(true)>]
type COMException = 
    class
        inherit ExternalException
    end

<SerializableAttribute>
<ComVisibleAttribute(True)>
Public Class COMException
    Inherits ExternalException

Construtores

	Nome	Descrição
	COMException()	Inicializa uma nova instância da classe COMException com valores padrão.
	COMException(SerializationInfo, StreamingContext)	Inicializa uma nova instância da classe COMException dos dados de serialização.
	COMException(String)	Inicializa uma nova instância da classe COMException com uma mensagem especificada.
	COMException(String, Exception)	Inicializa uma nova instância da classe COMException com uma mensagem de erro especificada e uma referência à exceção interna que é a causa da exceção.
	COMException(String, Int32)	Inicializa uma nova instância da classe COMException com uma mensagem e um código de erro especificados.

Propriedades

	Nome	Descrição
	Data	Obtém uma coleção de pares de chave/valor que fornecem informações adicionais definidas pelo usuário sobre a exceção.(Herdado de Exception.)
	ErrorCode	Obtém o HRESULT do erro.(Herdado de ExternalException.)
	HelpLink	Obtém ou define um link para o arquivo de ajuda associado a essa exceção.(Herdado de Exception.)
	HResult	Obtém ou define HRESULT, um valor numérico codificado que é atribuído a uma exceção específica.(Herdado de Exception.)
	InnerException	Obtém a instância Exception que causou a exceção atual.(Herdado de Exception.)
	Message	Obtém uma mensagem que descreve a exceção atual.(Herdado de Exception.)
	Source	Obtém ou define o nome do aplicativo ou objeto que causa o erro.(Herdado de Exception.)
	StackTrace	Obtém uma representação de cadeia de caracteres de quadros imediatos na pilha de chamadas.(Herdado de Exception.)
	TargetSite	Obtém o método que gerou a exceção atual.(Herdado de Exception.)

Métodos

	Nome	Descrição
	Equals(Object)	Determina se o objeto especificado é igual ao objeto atual.(Herdado de Object.)
	Finalize()	Permite que um objeto tente liberar recursos e executar outras operações de limpeza antes de ser recuperado pela coleta de lixo.(Herdado de Object.)
	GetBaseException()	Quando substituído em uma classe derivada, retorna a Exception que é a causa raiz de uma ou mais exceções subsequentes.(Herdado de Exception.)
	GetHashCode()	Serve como a função de hash padrão.(Herdado de Object.)
	GetObjectData(SerializationInfo, StreamingContext)	Quando substituído em uma classe derivada, define o SerializationInfo com informações sobre a exceção.(Herdado de Exception.)
	GetType()	Obtém o tipo de tempo de execução da instância atual.(Herdado de Exception.)
	MemberwiseClone()	Cria uma cópia superficial do Object atual.(Herdado de Object.)
	ToString()	Converte o conteúdo da exceção em uma cadeia de caracteres.(Substitui o ExternalException.ToString().)

Eventos

	Nome	Descrição
	SerializeObjectState	Ocorre quando uma exceção é serializada para criar um objeto de estado de exceção que contém dados serializados sobre a exceção.(Herdado de Exception.)

Comentários

O common language runtime transforma conhecidos HRESULTs em exceções do .NET Framework, permitindo que os objetos retornar informações de erro significativas para os clientes gerenciados. O HRESULT para mapeamento de exceção também funciona na outra direção, retornando HRESULTs específicos para clientes não gerenciados. Para obter detalhes de mapeamento, consulte Como mapear HRESULTs e exceções.

Quando o tempo de execução encontra um HRESULT desconhecido (um HRESULT que não tem uma exceção específica, correspondente), ele gera uma instância do COMException classe. Essa exceção multifuncional expõe os mesmos membros da exceção e herda um público ErrorCode propriedade que contenha o HRESULT retornado pelo receptor. Se uma mensagem de erro está disponível para o tempo de execução (obtido o IErrorInfo interface ou Err objeto no Visual Basic ou, em alguns casos do sistema operacional), a mensagem é retornada para o chamador. No entanto, se o desenvolvedor do componente COM não incluir uma mensagem de erro, o tempo de execução retornará o HRESULT de oito dígitos no lugar de uma cadeia de caracteres de mensagem. Ter um HRESULT permite que o chamador determinar a causa da exceção genérica.

Tratando uma exceção COMException

A seguir estão algumas considerações para solucionar problemas de um COMException exceção.

• Verifique o ErrorCode propriedade
  Quando o tempo de execução encontra um HRESULT desconhecido e lança um COMException exceção, o ErrorCode propriedade inclui a mensagem de erro ou, se uma mensagem de erro não estiver disponível, o valor HRESULT de oito dígitos. A mensagem de erro ou o valor HRESULT pode ajudá-lo a determinar a causa da exceção.

  Para obter uma lista de valores HRESULT, consulte Common HRESULT Values.

• Argumentos de associação tardia e objetos do Microsoft Office
  Ao passar argumentos de associação tardia para métodos de objetos do Microsoft Office, um COMException exceção pode ser lançada quando os objetos são objetos COM. A associação tardia presume que essas chamadas de método envolvem um parâmetro ByRef e que a propriedade passada por você tem um acessador set. Se a propriedade não existir, o .NET Framework gera um MissingMethodException exceção (com um CORE_E_MISSINGMETHOD HRESULT). Para contornar esse comportamento, use objetos de associação antecipada ou passe uma variável em vez de uma propriedade do objeto.

• O Visual Studio e o processo de hospedagem
  COM é usado para comunicação entre o Visual Studio e o hosting process. Porque ele é usado antes de executar o código, uma chamada para CoInitializeSecurity faz com que essa exceção seja lançada.

  Em alguns casos, executando o Visual Studio como administrador pode resolver o problema. Você também pode disable the hosting process.

Gerar uma exceção de COMException

Embora você possa usar o COMException classe para retornar HRESULTs específicos para clientes não gerenciados, lançando uma exceção específica do .NET Framework é melhor do que usando uma exceção genérica. Considere a possibilidade de que clientes gerenciados, bem como os clientes não gerenciados podem usar o objeto do .NET Framework e lançar um HRESULT para um chamador gerenciado é menos abrangente que gerar uma exceção.

Informações de Versão

Plataforma Universal do Windows
Disponível desde 8
.NET Framework
Disponível desde 1.1
Biblioteca de Classes Portátil
Com suporte no: plataformas portáteis do .NET
Silverlight
Disponível desde 2.0
Windows Phone Silverlight
Disponível desde 7.0
Windows Phone
Disponível desde 8.1

Acesso thread-safe

Quaisquer membros estáticos públicos ( Compartilhado no Visual Basic) desse tipo são thread-safe. Não há garantia de que qualquer membro de instância seja thread-safe.

Confira Também

Exception
Namespace System.Runtime.InteropServices
Manipulando e lançando exceções

Retornar ao início