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

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 dei fogli di lavoro nella cartella di lavoro personalizzata, ma non quando l'utente attiva un foglio di lavoro in altre cartelle di lavoro che possono essere aperte contemporaneamente.

Quando è presente un oggetto nativo di Office, è possibile verificare se tale oggetto è stato esteso in un elemento host o in un controllo host di una personalizzazione a livello di documento. Gli elementi e i controlli host sono tipi forniti da Runtime 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 i controlli host, vedere Cenni preliminari sugli elementi e sui controlli host.

Si applica a: le informazioni fornite in questo argomento sono valide per i progetti a livello di documento per Excel 2007, Excel 2010, Word 2007 e Word 2010. Per ulteriori informazioni, vedere Funzionalità disponibili in base ai tipi di progetto e applicazioni di Office.

Informazioni sui metodi GetVstoObject e HasVstoObject

Per eseguire il test di un oggetto nativo di Office, utilizzare i metodi HasVstoObject e GetVstoObject nel progetto:

• Se si desidera 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 per un oggetto nativo di Office, 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 specificato ne dispone di uno. In caso contrario, GetVstoObject restituisce null. Ad esempio, il metodo GetVstoObject restituisce un oggetto Microsoft.Office.Tools.Word.Document se l'oggetto Microsoft.Office.Interop.Word.Document specificato è l'oggetto sottostante del documento nel progetto documento di Word.

Nei progetti a livello di documento non è possibile utilizzare il metodo GetVstoObject per creare un nuovo elemento host Microsoft.Office.Tools.Excel.Workbook, Microsoft.Office.Tools.Excel.Worksheet o Microsoft.Office.Tools.Word.Document in fase di esecuzione. Tale metodo può essere utilizzato solo per accedere agli elementi host esistenti generati nel progetto in fase di progettazione. Se si desidera creare nuovi elementi host in fase di esecuzione, è necessario sviluppare un progetto a livello di applicazione. Per ulteriori informazioni, vedere Limitazioni a livello di codice degli elementi e dei controlli host e Estensione in fase di esecuzione di documenti di Word e di cartelle di lavoro di Excel in componenti aggiuntivi a livello di applicazione.

Utilizzo dei metodi GetVstoObject e HasVstoObject

Il modo in cui si chiamano i metodi HasVstoObject e GetVstoObject dipende dalla versione di .NET Framework a cui è destinato il progetto:

• In progetti che vengono destinati a .NET Framework 4, utilizzare il metodo Globals.Factory.GetVstoObject o Globals.Factory.HasVstoObject e passare l'oggetto nativo di Word o di Excel (ad esempio, un oggetto Microsoft.Office.Interop.Word.Document o Microsoft.Office.Interop.Excel.Worksheet) che si desidera sottoporre a test.

• In progetti destinati a .NET Framework 3.5, accedere ai metodi in un'istanza di uno dei tipi seguenti negli assembly di interoperabilità primari di Excel e di Word:

  • Oggetto Microsoft.Office.Interop.Excel.ListObject.

  • Oggetto Microsoft.Office.Interop.Excel.Workbook.

  • Oggetto Microsoft.Office.Interop.Excel.Worksheet.

  • Oggetto Microsoft.Office.Interop.Word.Document.

Esempio: 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.Base
    ElseIf Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet2.Base
    ElseIf Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh) Then
        vstoWorksheet = Globals.Sheet3.Base
    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.Base;
    else if (Type.ReferenceEquals(Globals.Sheet2.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet2.Base;
    else if (Type.ReferenceEquals(Globals.Sheet3.InnerObject, Sh))
        vstoWorksheet = Globals.Sheet3.Base;

    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. In questo esempio viene dimostrato come chiamare tali metodi in un progetto destinato a .NET Framework 4.

Private Sub ThisWorkbook_SheetActivate2(ByVal Sh As Object)
    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
        Globals.Factory.HasVstoObject(interopWorksheet) Then
        vstoWorksheet = Globals.Factory.GetVstoObject(interopWorksheet)
    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 && Globals.Factory.HasVstoObject(interopWorksheet))
    {
        vstoWorksheet = Globals.Factory.GetVstoObject(interopWorksheet);
    }

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

Nell'esempio riportato di seguito viene dimostrata la stessa attività in un progetto destinato a .NET Framework 3.5.

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.
    }
}

Vedere anche

Riferimenti

Metodi di estensione (Guida per programmatori C#)

Concetti

Cenni preliminari sugli elementi e sui controlli host

Estensione in fase di esecuzione di documenti di Word e di cartelle di lavoro di Excel in componenti aggiuntivi a livello di applicazione

Metodi di estensione (Visual Basic)

Altre risorse

Programmazione delle personalizzazioni a livello di documento