IVsDataProvider.TryCreateObject<TSite> Method (Guid, Type, TSite)

Article
10/02/2013

Tries to create an instance of the specified DDEX support entity for the specified DDEX data source that is implemented by the DDEX provider, sited with the specified site object.

Namespace: Microsoft.VisualStudio.Data.Core
Assembly: Microsoft.VisualStudio.Data.Core (in Microsoft.VisualStudio.Data.Core.dll)

Syntax

'Declaration
Function TryCreateObject(Of TSite) ( _
    source As Guid, _
    objType As Type, _
    site As TSite _
) As Object

Object TryCreateObject<TSite>(
    Guid source,
    Type objType,
    TSite site
)

generic<typename TSite>
Object^ TryCreateObject(
    Guid source, 
    Type^ objType, 
    TSite site
)

abstract TryCreateObject : 
        source:Guid * 
        objType:Type * 
        site:'TSite -> Object

JScript does not support generic types or methods.

Type Parameters

TSite
The site.

Parameters

source
Type: System.Guid

A DDEX data source identifier, or Empty for no specific data source.

objType
Type: System.Type

A type of DDEX support entity.

site
Type: TSite

An instance of an object that should site the new DDEX support entity.

Return Value

Type: System.Object
An instance of the specified DDEX support entity that is implemented by the DDEX provider, sited with the specified site object, if the DDEX provider supports it; otherwise, nulla null reference (Nothing in Visual Basic).

Exceptions

Exception	Condition
ArgumentNullException	The objType parameter is nulla null reference (Nothing in Visual Basic).
DataProviderException	Instantiation of a new instance of the support entity threw an exception, whether by way of a CreateInstance call through reflection or through the DDEX provider’s CreateObject or CreateObject method implementation, or creation of the default or client object implementation (if there is one) failed.

Remarks

This method performs various steps to produce an instance of the specified DDEX support entity type.

Registry Inspection

The method starts by inspecting the registry for information about this support entity. It looks under the provider’s SupportedObjects key for a registry key that matches the support entity type. If a non-empty DDEX data source was passed into the method, it also looks for a subkey for this DDEX data source. If either key is found, it retrieves the default value of the key. If the value of the key is non-nulla null reference (Nothing in Visual Basic) and non-empty, it assumes the value to be the type name of a class that implements the support entity. It then retrieves qualifying information, starting with a CodeBase value, and, if this is nulla null reference (Nothing in Visual Basic), an Assembly value. The CodeBase value is the fully qualified path of an assembly that contains the registered type. The Assembly value is the fully qualified name of an assembly that can be located and loaded by the common language runtime (CLR).

If the support entity inherits from the base IVsDataSupport interface, whose sole purpose is to return a stream of XML, the method looks for additional values that may describe the location of an XML file that can be passed to a base implementation of the specific support entity. One example would be the DataObjectSupport class that is defined in the standard DDEX framework assembly. The method first looks for an XmlFile value that may or may not be the fully qualified name of an XML file on disk. If this value exists, the method looks for an XmlPath value that may contain the path of an unqualified XmlFile value. The separation of path and file name is important when you are putting localized versions of an XML file at the same path location. If no XmlFile value exists, the method looks for an XmlResource value that identifies the name of a resource that contains XML in an assembly. It then then looks for qualifying information, starting with an XmlCodeBase value, and, if this is nulla null reference (Nothing in Visual Basic), an XmlAssembly value. The XmlCodeBase value is the fully qualified path of an assembly that contains the specified resource. The XmlAssembly value is the fully qualified name of an assembly that can be located and loaded by the CLR.

If at this point it is determined that there is not enough information in the registry to create an instance of the DDEX support entity, the registry inspection step is skipped. In this case, the method falls back to an explicit implementation of the IVsDataSourceSpecializer or IVsDataProviderObjectFactory interface, if it is implemented by the DDEX provider. Otherwise, the method loads the appropriate assembly through codebase or full name (in that order) and gets the type from the assembly. If this process does not find an appropriate type, a DataProviderException is thrown.

Finally, an instance of the type is created. If the support entity inherits from the base IVsDataSupport interface and additional information about an XML file location has been registered by the provider, this information is passed as arguments to the type constructor. This information is passed either as the XML file name and path (two strings), or as the XML resource name and resolved Assembly object (a string and an Assembly object). In the latter case, a DataProviderException is thrown if the assembly cannot be loaded. If any other error occurs when the type instance is being created, or the created type does not implement the expected support entity type, a DataProviderException is thrown.

Call Source Specializer or Provider Object Factory

When registry inspection does not find enough information to create an instance of the support entity, the DDEX provider’s source specializer (if one exists) or object factory (for a package-based provider) CreateObject method is called. When a non-empty DDEX data source is passed to this method, the provider’s source specializer (if one exists) is called first. If this method throws a NotImplementedException or returns no new instance, it calls the provider’s object factory, if there is one, also ignoring any NotImplementedException that is thrown. For all other exceptions, a DataProviderException is thrown.

Create Default Instance

If no object has been created by this point, this means that the DDEX provider does not implement the support entity. However, if the support entity defines a default object implementation, an instance of the default object will be created.

Note

DDEX in Visual Studio 2005 does not support default object implementation, so no default object will be created.

Object Siting

All newly created instances of DDEX support entities that use this method can be sited with three standard site objects. These objects are as follows: a global service provider object, the IVsDataProvider object that created it, and the IVsDataSource object that represents the specific DDEX data source that it was created for, if a non-empty DDEX data source was provided. Instances are sited only when the newly created instance implements the IVsDataSiteableObject<T> interface with the generic types IServiceProvider, IVsDataProvider, and/or IVsDataSource, respectively.

Following these standard site objects, if a custom site object is passed in by the caller, the new instance will be sited with the custom object when it implements the IVsDataSiteableObject<T> interface.

Client Object Creation

The final step in creating a DDEX support entity involves producing a client wrapper object if the entity is defined with one. This is done by first inspecting the support entity type for an instance of DataClientObjectAttribute. If this instance exists, an instance of the object identified by the associated class ID is created and the new provider object is passed to this client object. After client objects are created, they are sited with the same set of standard and custom site objects that the underlying provider object was offered.

Examples

The following code demonstrates how to call this method to create one of the standard support entities.

using System;
using Microsoft.VisualStudio.Data.Core;
using Microsoft.VisualStudio.Data.Services.SupportEntities;

public class DDEX_IVsDataProviderExample10
{
    public static IVsDataConnectionProperties CreateConnectionProperties(
        IVsDataProvider provider)
    {
        return provider.TryCreateObject<IVsDataConnectionProperties>();
    }
}

.NET Framework Security

Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.

Partager via