Limitazioni a livello di codice degli elementi e dei controlli host

Articolo
08/11/2011

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 2007, Excel 2010, Word 2007 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 esistono due casi in cui è necessario utilizzare la proprietà InnerObject del controllo host per passare il controllo host a un metodo o proprietà:

Quando il metodo o la proprietà prevede l'oggetto Excel sottostante.
Quando l'attributo Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute viene impostato su false in un progetto destinato a .NET Framework 3.5 e il metodo o la proprietà prevede un oggetto Object anziché l'oggetto di Excel sottostante. Per ulteriori informazioni su Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute, vedere Formattazione di dati in Excel con varie impostazioni internazionali.

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", missing].Value2 = "Monday";
this.Range["A2", missing].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 agli insiemi di controlli host

Il Runtime di Visual Studio Tools per Office non fornisce insiemi specifici 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 insiemi 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.

Accesso ai nuovi membri di Excel 2010 e Word 2010 nei progetti destinati a .NET Framework 3.5

Nei progetti di Excel 2010 e Word 2010 destinati a .NET Framework 3.5, i membri introdotti in Office 2010 non sono disponibili negli elementi host e nei controlli host. In questi progetti, gli elementi host e i controlli host dispongono unicamente di membri disponibili in Microsoft Office System 2007. Per accedere a un membro aggiunto in Excel 2010 o Word 2010, utilizzare la proprietà InnerObject del controllo host per restituire l'oggetto nativo sottostante, quindi accedere al membro in quell'oggetto.

Ad esempio, in Word 2010, gli oggetti Microsoft.Office.Interop.Word.ContentControl dispongono di una proprietà Checked che può essere utilizzata per determinare se viene selezionato un controllo contenuto della casella di controllo (questa proprietà non è disponibile in Word 2007 perché Word 2007 non dispone di controlli del contenuto della casella di controllo). Nei progetti di Word 2010 destinati a .NET Framework 3.5, il controllo host Microsoft.Office.Tools.Word.ContentControl non dispone di una proprietà Checked. Nell'esempio di codice riportato di seguito viene illustrato come utilizzare la proprietà InnerObject per accedere alla proprietà Checked dell'oggetto Microsoft.Office.Interop.Word.ContentControl sottostante.

Me.Paragraphs(1).Range.InsertParagraphBefore()
Me.Paragraphs(1).Range.Select()
Dim checkBoxControl1 As Microsoft.Office.Tools.Word.ContentControl =
    Me.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox)

' The following line of code compiles in projects that target the .NET Framework 4, but it does not compile 
' in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = True

' In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = True

this.Paragraphs[1].Range.InsertParagraphBefore();
this.Paragraphs[1].Range.Select();
Microsoft.Office.Tools.Word.ContentControl checkBoxControl1 = 
    this.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox);

// The following line of code compiles in projects that target the .NET Framework 4, but it does not compile 
// in projects that target the .NET Framework 3.5.
checkBoxControl1.Checked = true;

// In projects that target the .NET Framework 3.5, use the following code.
checkBoxControl1.InnerObject.Checked = true;