Limitazioni a livello di codice degli elementi host e dei controlli host

  • Articolo

Ogni 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 Panoramica degli elementi host e dei controlli host.

Si applica a: le informazioni contenute in questo argomento si applicano ai progetti a livello di documento e ai progetti di componente aggiuntivo VSTO per Excel e Word. Per altre informazioni, vedere Funzionalità disponibili per app Office lication e tipo di progetto.

Creare elementi host a livello di codice

Quando si crea o si apre a livello di codice un documento, 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 è un elemento host. Al contrario, si tratta di un nuovo oggetto nativo di Office. Ad esempio, se si usa il metodo Add per creare un nuovo documento di Word in fase di esecuzione, si tratterà di un oggetto Document nativo piuttosto che di un elemento host Document . Analogamente, quando si crea un nuovo foglio di lavoro in fase di esecuzione usando il metodo Add , si ottiene un oggetto Worksheet nativo piuttosto che un elemento host 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 altre informazioni, vedere Elemento host documento, elemento host cartella di lavoro e elemento host foglio di lavoro.

Nei progetti di componente aggiuntivo VSTO è possibile creare elementi host Document, Workbooko Worksheet in fase di esecuzione. Per altre informazioni, vedere Estendere documenti di Word e cartelle di lavoro di Excel nei componenti aggiuntivi VSTO in fase di esecuzione.

Creare controlli host a livello di codice

È possibile aggiungere a livello di codice controlli host a un elemento host Document o Worksheet in fase di esecuzione. Per altre informazioni, vedere Aggiungere controlli ai documenti di Office in fase di esecuzione.

Non è possibile aggiungere controlli host a un oggetto Document o Worksheetnativo.

Nota

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

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

Per ogni elemento host e controllo host esiste un oggetto nativo di Microsoft Office Word o Microsoft Office Excel sottostante. È possibile accedere all'oggetto sottostante usando 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 prova a 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.

Passare 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 nativo di Word come parametro. È necessario utilizzare la proprietà InnerObject del controllo host per restituire l'oggetto Word nativo sottostante. Ad esempio, è possibile passare un oggetto Bookmark a un metodo passando la proprietà InnerObject del controllo host Bookmark al metodo.

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

L'esempio seguente crea un controllo NamedRange e lo passa al metodo AutoFill . Il codice usa la proprietà InnerObject dell'intervallo denominato per restituire l'oggetto Range di Office sottostante richiesto dal metodo AutoFill .

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);

Restituire tipi di metodi e proprietà 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 Worksheet piuttosto che un elemento host Worksheet . Analogamente, la proprietà Parent di un controllo host RichTextContentControl in Word restituisce un oggetto Document piuttosto che un elemento host Document .

Accedere alle raccolte di controlli host

Il Strumenti di Visual Studio per il runtime di Office non fornisce singole raccolte per ogni tipo di controllo host. Utilizzare invece la proprietà Controls di un elemento host per scorrere tutti i controlli gestiti (sia i controlli host che i controlli Windows Form) nel documento o nel foglio di lavoro, quindi cercare gli elementi che corrispondono al tipo del controllo host a cui si è interessati. L'esempio di codice seguente esamina ogni controllo in un documento di Word e determina se il controllo è di tipo Bookmark.

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 altre informazioni sulla proprietà Controls degli elementi host, vedere Aggiungere 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 Bookmark in un documento tramite la proprietà Bookmarks di un oggetto Document o la proprietà Bookmarks di un oggetto Document. Queste proprietà includono solo i controlli Bookmark nel documento; non contengono i controlli host Bookmark nel documento.

Contenuto correlato