Limitazioni a livello di codice degli elementi e dei controlli host

Articolo
02/19/2013

Ciascun elemento host e controllo host viene progettato per comportarsi come un oggetto nativo corrispondente di Microsoft Office Word o Microsoft Office Excel, con funzionalità aggiuntive.Tuttavia, esistono alcune differenze fondamentali tra il comportamento degli elementi host e dei controlli host e gli oggetti nativi di Office in fase di esecuzione.

Per informazioni generali sugli elementi host e sui 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 e di applicazione per Excel 2013, Excel 2010, Word 2013 e Word 2010. Per ulteriori informazioni, vedere Funzionalità disponibili in base ai tipi di progetto e applicazioni di Office.

Creazione a livello di codice di elementi host

Quando si crea o si apre un documento a livello di codice, una cartella di lavoro o un foglio di lavoro in fase di esecuzione mediante il modello a oggetti di Word o Excel, l'elemento non è di tipo host.Al contrario, si tratta di un nuovo oggetto nativo di Office.Ad esempio, se si utilizza il metodo Documents.Add per creare un nuovo documento di Word in fase di esecuzione, si tratterà di un oggetto Microsoft.Office.Interop.Word.Document nativo piuttosto che di un elemento host Microsoft.Office.Tools.Word.Document.Analogamente, quando si crea un nuovo foglio di lavoro in fase di esecuzione utilizzando il metodo Worksheets.Add, si ottiene un oggetto Microsoft.Office.Interop.Excel.Worksheet nativo piuttosto che un elemento host Microsoft.Office.Tools.Excel.Worksheet.

Nei progetti a livello di documento, non è possibile creare elementi host in fase di esecuzione.Gli elementi host possono essere creati solo in fase di progettazione nei progetti a livello di documento.Per ulteriori informazioni, vedere Elemento host documento, Elemento host cartella di lavoro e Elemento host foglio di lavoro.

Nei progetti a livello di applicazione è possibile creare elementi host Microsoft.Office.Tools.Word.Document, Microsoft.Office.Tools.Excel.Workbook o Microsoft.Office.Tools.Excel.Worksheet in fase di esecuzione.Per ulteriori informazioni, vedere Estensione in fase di esecuzione di documenti di Word e di cartelle di lavoro di Excel in componenti aggiuntivi a livello di applicazione.

Creazione a livello di codice di controlli host

È possibile aggiungere a livello di codice controlli host a un elemento host Microsoft.Office.Tools.Word.Document o Microsoft.Office.Tools.Excel.Worksheet in fase di esecuzione.Per ulteriori informazioni, vedere Aggiunta di controlli ai documenti di Office in fase di esecuzione.

Non è possibile aggiungere controlli host a un oggetto Microsoft.Office.Interop.Word.Document o Microsoft.Office.Interop.Excel.Worksheet nativo.

[!NOTA]

I controlli host seguenti non possono essere aggiunti a livello di codice a fogli di lavoro o documenti: XmlMappedRange, XMLNode e XMLNodes.

Informazioni sulle differenze di tipo tra elementi host, controlli host e oggetti nativi di Office

Per ciascun elemento host e controllo host esiste un oggetto nativo di Microsoft Office Word o Microsoft Office Excel sottostante.È possibile accedere all'oggetto sottostante utilizzando la proprietà InnerObject dell'elemento host o del controllo host.Non esiste tuttavia alcun modo per eseguire il cast di un oggetto nativo di Office nel corrispondente elemento host o controllo host.Se si tenta di eseguire il cast di un oggetto nativo di Office nel tipo di un elemento host o di un controllo host, verrà generata un'eccezione InvalidCastException.

Esistono diversi scenari in cui le differenze tra i tipi di elementi host e controlli host e gli oggetti nativi di Office sottostanti possono influire sul codice.

Passaggio di controlli host a metodi e proprietà

In Word non è possibile passare un controllo host a un metodo o a una proprietà che richiede un oggetto Word nativo come parametro.È necessario utilizzare la proprietà InnerObject del controllo host per restituire l'oggetto Word nativo sottostante.Ad esempio, è possibile passare un oggetto Microsoft.Office.Interop.Word.Bookmark a un metodo passando la proprietà InnerObject del controllo host Microsoft.Office.Tools.Word.Bookmark al metodo.

In Excel, è necessario utilizzare la proprietà InnerObject del controllo host per passare il controllo host a un metodo o una proprietà quando il metodo o la proprietà prevede l'oggetto di Excel sottostante.

Nell'esempio riportato di seguito un controllo Microsoft.Office.Tools.Excel.NamedRange viene creato e passato al metodo AutoFill.Il codice utilizza la proprietà InnerObject dell'intervallo denominato per restituire l'oggetto Microsoft.Office.Interop.Excel.Range di Office sottostante richiesto dal metodo AutoFill.

Me.Range("A1").Value2 = "Monday"
Me.Range("A2").Value2 = "Tuesday"

Dim dayRange As Microsoft.Office.Tools.Excel.NamedRange = _
    Me.Controls.AddNamedRange(Me.Range("A1", "A7"), "dayRange")
Me.Range("A1", "A2").AutoFill(dayRange.InnerObject, Excel.XlAutoFillType.xlFillDays)

this.Range["A1"].Value2 = "Monday";
this.Range["A2"].Value2 = "Tuesday";

Microsoft.Office.Tools.Excel.NamedRange dayRange = 
    this.Controls.AddNamedRange(this.Range["A1", "A7"], "dayRange");
this.Range["A1", "A2"].AutoFill(dayRange.InnerObject, Excel.XlAutoFillType.xlFillDays);

Tipi restituiti delle proprietà e dei metodi nativi di Office

La maggior parte dei metodi e delle proprietà degli elementi host restituisce l'oggetto nativo di Office sottostante sul quale si basa l'elemento host.Ad esempio, la proprietà Parent di un controllo host NamedRange in Excel restituisce un oggetto Microsoft.Office.Interop.Excel.Worksheet piuttosto che un elemento host Microsoft.Office.Tools.Excel.Worksheet.Analogamente, la proprietà Parent di un controllo host RichTextContentControl in Word restituisce un oggetto Microsoft.Office.Interop.Word.Document piuttosto che un elemento host Microsoft.Office.Tools.Word.Document.

Accesso alle raccolte di controlli host

Il Runtime di Visual Studio Tools per Office non fornisce raccolte specifiche per ogni tipo di controllo host.Utilizzare invece la proprietà Controls di un elemento host per scorrere tutti i controlli gestiti (controlli host e controlli Windows Form) nel documento o nel foglio di lavoro, quindi cercare gli elementi che corrispondono al tipo di controllo host a cui si è interessati.Nell'esempio di codice seguente viene esaminato ciascun controllo in un documento di Word e viene stabilito se il controllo è di tipo Microsoft.Office.Tools.Word.Bookmark.

Dim targetControl As Object
For Each targetControl In Me.Controls

    If TypeOf (targetControl) Is Microsoft.Office.Tools.Word.Bookmark Then
        Dim bookMark As Microsoft.Office.Tools.Word.Bookmark = _
            CType(targetControl, Microsoft.Office.Tools.Word.Bookmark)

        ' Do some work with the book mark here.
    End If
Next

foreach (object targetControl in this.Controls)
{
    Microsoft.Office.Tools.Word.Bookmark bookMark =
        targetControl as Microsoft.Office.Tools.Word.Bookmark;

    if (bookMark != null)
    {
        // Do some work with the bookmark here.
    }
}

Per ulteriori informazioni sulla proprietà Controls degli elementi host, vedere Aggiunta di controlli ai documenti di Office in fase di esecuzione.

I modelli a oggetti di Word ed Excel includono proprietà che espongono raccolte di controlli nativi in documenti e fogli di lavoro.Non è possibile accedere ai controlli gestiti tramite queste proprietà.Ad esempio, non è possibile enumerare ogni controllo host Microsoft.Office.Tools.Word.Bookmark in un documento tramite la proprietà Bookmarks di un oggetto Microsoft.Office.Interop.Word.Document o la proprietà Bookmarks di un oggetto Microsoft.Office.Tools.Word.Document.Queste proprietà includono solo i controlli Microsoft.Office.Interop.Word.Bookmark nel documento; non contengono i controlli host Microsoft.Office.Tools.Word.Bookmark nel documento.