Recupero di oggetti estesi da oggetti nativi di Office nelle personalizzazioni a livello di documento

Articolo
04/28/2010

Aggiornamento: Luglio 2008

Si applica a
Le informazioni contenute in questo argomento riguardano solo i progetti Visual Studio Tools per Office e le versioni di Microsoft Office specificati. Tipo di progetto Progetti a livello di documento Versione Microsoft Office Excel 2007 Word 2007 Per ulteriori informazioni, vedere la classe Funzionalità disponibili in base ai tipi di progetto e applicazione.

Le informazioni contenute in questo argomento riguardano solo i progetti Visual Studio Tools per Office e le versioni di Microsoft Office specificati.

Tipo di progetto

Progetti a livello di documento

Versione Microsoft Office

Excel 2007
Word 2007

Per ulteriori informazioni, vedere la classe Funzionalità disponibili in base ai tipi di progetto e applicazione.

Molti gestori degli eventi di Office ricevono un oggetto nativo di Office che rappresenta la cartella di lavoro, il foglio di lavoro o il documento che ha generato l'evento. In alcuni casi, è necessario eseguire il codice solo se l'evento è stato generato dalla cartella di lavoro o dal documento della personalizzazione a livello di documento. Ad esempio, in una personalizzazione a livello di documento per Excel, è necessario eseguire il codice quando l'utente attiva uno degli elementi host Microsoft.Office.Tools.Excel.Worksheet nella personalizzazione, ma non quando l'utente attiva un foglio di lavoro in altre cartelle di lavoro che possono essere aperte contemporaneamente.

A partire da Visual Studio 2008 Service Pack 1 (SP1), quando si ottiene un oggetto nativo di Office, è possibile verificare se tale oggetto è stato esteso in un elemento host o in un controllo host Microsoft.Office.Tools.Excel.ListObject di una personalizzazione a livello di documento.

Gli elementi e i controlli host sono oggetti di Visual Studio Tools per Office che consentono di aggiungere funzionalità a oggetti che esistono a livello nativo nei modelli a oggetti di Word o di Excel (chiamati oggetti nativi di Office). Collettivamente, gli elementi host e i controlli host vengono anche definiti oggetti estesi. Per ulteriori informazioni sugli elementi host e sui controlli host, vedere Cenni preliminari sugli elementi e sui controlli host.

Utilizzo dei metodi GetVstoObject e HasVstoObject

Per verificare un oggetto nativo di Office, utilizzare i metodi HasVstoObject e GetVstoObject di un'istanza di uno dei seguenti oggetti nativi di Office:

Oggetto Microsoft.Office.Interop.Excel.ListObject.
Oggetto Microsoft.Office.Interop.Excel.Workbook.
Oggetto Microsoft.Office.Interop.Excel.Worksheet.
Oggetto Microsoft.Office.Interop.Word.Document.

Se si desidera solo determinare se l'oggetto nativo di Office dispone di un oggetto esteso nella personalizzazione, utilizzare il metodo HasVstoObject. Questo metodo restituisce true se l'oggetto nativo di Office dispone di un oggetto esteso, altrimenti false.

Se si desidera ottenere l'oggetto esteso, utilizzare il metodo GetVstoObject. Questo metodo restituisce un oggetto Microsoft.Office.Tools.Excel.ListObject, Microsoft.Office.Tools.Excel.Workbook, Microsoft.Office.Tools.Excel.Worksheet o Microsoft.Office.Tools.Word.Document se l'oggetto nativo di Office ne dispone di uno. In caso contrario, GetVstoObject restituisce null. Ad esempio, il metodo GetVstoObject di un oggetto Microsoft.Office.Interop.Word.Document restituisce un oggetto Microsoft.Office.Tools.Word.Document se l'oggetto Microsoft.Office.Interop.Word.Document è l'oggetto sottostante per il documento del progetto Documento di Word.

Non è possibile utilizzare l'oggetto GetVstoObject in una soluzione a livello di documento per creare un nuovo elemento host in fase di esecuzione. Tale oggetto può essere utilizzato solo per accedere agli elementi host generati nel progetto in fase di progettazione. Per ulteriori informazioni, vedere la classe Limitazioni a livello di codice degli elementi e dei controlli host.

Nei progetti a livello di applicazione, è possibile utilizzare il metodo GetVstoObject per generare nuovi elementi host in fase di esecuzione. Per ulteriori informazioni, vedere la classe Estensione in fase di esecuzione di documenti di Word e di cartelle di lavoro di Excel in componenti aggiuntivi a livello di applicazione.

Nota:
Per utilizzare i metodi GetVstoObject e HasVstoObject, è necessario aggiungere le istruzioni using (per C#) o Imports (per Visual Basic) per gli spazi dei nomi Microsoft.Office.Tools.Excel.Extensions o Microsoft.Office.Tools.Word.Extensions all'inizio del file di codice. I metodi GetVstoObject e HasVstoObject vengono implementati come metodi di estensione nel runtime di Visual Studio Tools per Office e le istruzioni consentono di chiamare questi metodi.

Per utilizzare i metodi GetVstoObject e HasVstoObject, è necessario aggiungere le istruzioni using (per C#) o Imports (per Visual Basic) per gli spazi dei nomi Microsoft.Office.Tools.Excel.Extensions o Microsoft.Office.Tools.Word.Extensions all'inizio del file di codice. I metodi GetVstoObject e HasVstoObject vengono implementati come metodi di estensione nel runtime di Visual Studio Tools per Office e le istruzioni consentono di chiamare questi metodi.

Determinazione dell'eventuale generazione di un evento da parte di un elemento host

Negli esempi di codice seguenti vengono illustrati i metodi HasVstoObject e GetVstoObject. In entrambi gli esempi viene gestito l'evento SheetActivate della classe ThisWorkbook in un progetto Cartella di lavoro di Excel.

Il primo esempio determina se uno degli elementi host Microsoft.Office.Tools.Excel.Worksheet è stato attivato confrontando il parametro Sh con la proprietà InnerObject di ogni elemento host predefinito.

Sub ThisWorkbook_SheetActivate1(ByVal Sh As Object) Handles Me.SheetActivate
    Dim vstoWorksheet As Microsoft.Office.Tools.Excel.Worksheet = Nothing

    If Type.ReferenceEquals(Globals.Sheet1.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet1
    ElseIf Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet2
    ElseIf Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet3
    End If

    If vstoWorksheet IsNot Nothing Then
        ' Do something with the VSTO worksheet here.
    End If
End Sub

void ThisWorkbook_SheetActivate1(object Sh)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoWorksheet = null;

    if (Type.ReferenceEquals(Globals.Sheet1.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet1;
    else if (Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet2;
    else if (Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet3;

    if (vstoWorksheet != null)
    {
        // Do something with the VSTO worksheet here.
    }
}

Nell'esempio successivo, questo processo viene semplificato utilizzando i metodi HasVstoObject e GetVstoObject del parametro Sh.

Sub ThisWorkbook_SheetActivate2(ByVal Sh As Object) Handles Me.SheetActivate
    Dim vstoWorksheet As Microsoft.Office.Tools.Excel.Worksheet = Nothing
    Dim interopWorksheet As Microsoft.Office.Interop.Excel.Worksheet = _
        CType(Sh, Microsoft.Office.Interop.Excel.Worksheet)

    If interopWorksheet IsNot Nothing AndAlso _
        interopWorksheet.HasVstoObject() Then
        vstoWorksheet = interopWorksheet.GetVstoObject()
    End If

    If vstoWorksheet IsNot Nothing Then
        ' Do something with the VSTO worksheet here.
    End If
End Sub

void ThisWorkbook_SheetActivate2(object Sh)
{
    Microsoft.Office.Tools.Excel.Worksheet vstoWorksheet = null;
    Microsoft.Office.Interop.Excel.Worksheet interopWorksheet = 
        Sh as Microsoft.Office.Interop.Excel.Worksheet;

    if (interopWorksheet != null && interopWorksheet.HasVstoObject())
    {
        vstoWorksheet = interopWorksheet.GetVstoObject();
    }

    if (vstoWorksheet != null)
    {
        // Do something with the VSTO worksheet here.
    }
}