Metodo ServerDocument.AddCustomization (String, String, Guid, Uri)

Articolo
08/11/2011

Associa una personalizzazione al documento specificato utilizzando il documento, il nome assembly, l'ID soluzione e il manifesto di distribuzione specificati.

Spazio dei nomi: Microsoft.VisualStudio.Tools.Applications
Assembly: Microsoft.VisualStudio.Tools.Applications.ServerDocument (in Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll)

Sintassi

'Dichiarazione
Public Shared Sub AddCustomization ( _
    documentPath As String, _
    assemblyName As String, _
    solutionId As Guid, _
    deploymentManifestUrl As Uri _
)

public static void AddCustomization(
    string documentPath,
    string assemblyName,
    Guid solutionId,
    Uri deploymentManifestUrl
)

Parametri

documentPath
Tipo: System.String
Percorso completo del documento al quale si desidera associare una personalizzazione.

assemblyName
Tipo: System.String
Percorso completo dell'assembly per la personalizzazione.Il percorso deve essere nel file system locale o in una condivisione UNC. Non è possibile specificare un percorso HTTP.

solutionId
Tipo: System.Guid
GUID utilizzato da Runtime di Visual Studio Tools per Office per identificare la soluzione.

deploymentManifestUrl
Tipo: System.Uri
URL del manifesto di distribuzione per la soluzione.

Eccezioni

Eccezione	Condizione
ArgumentNullException	L'oggetto documentPath o assemblyName è nullriferimento null (Nothing in Visual Basic) o vuoto.
FileNotFoundException	documentPath o assemblyName fa riferimento a un file inesistente.
DocumentAlreadyCustomizedException	Il documento specificato da documentPath include già una personalizzazione.
DocumentNotCustomizedException	Il documento specificato da documentPath è corrotto oppure dispone di autorizzazioni limitate.
UnknownCustomizationFileException	L'estensione di file del documento specificata da documentPath non è supportata dal Runtime di Visual Studio Tools per Office.

Note

Il metodo AddCustomization associa al documento la personalizzazione specificata aggiungendo al documento le proprietà personalizzate _AssemblyName e _AssemblyLocation. Tali proprietà indicano che il documento è dotato di una personalizzazione e specificano il percorso del manifesto di distribuzione. Dolo la chiamata a questo metodo, la volta successiva che un utente apre il documento specificato, il runtime tenta di installare la soluzione Office. Per ulteriori informazioni sulle proprietà personalizzate dei documenti, vedere Cenni preliminari sulle proprietà personalizzate dei documenti.

Il GUID passato al parametro solutionID viene specificato nel manifesto dell'applicazione della soluzione che viene associata al documento. Deve essere passato lo stesso GUID specificato nell'attributo solutionId dell'elemento vstov4:document del manifesto dell'applicazione. Per ulteriori informazioni, vedere Manifesti dell'applicazione e di distribuzione nelle soluzioni di Office e Elemento <document> (sviluppo per Office in Visual Studio).

Se si esegue l'associazione di una personalizzazione da un percorso di pubblicazione, specificare il nome file corretto per l'assembly nel parametro assemblyName. Quando si pubblica una soluzione Office, il file di assembly copiato nella cartella di pubblicazione ha estensione deploy. Se ad esempio il nome dell'assembly è WordDocument1.dll, il nome file dell'assembly nella cartella di pubblicazione sarà WordDocument1.dll.deploy. Per ulteriori informazioni, vedere Pubblicazione di soluzioni Office.

Se il documento specificato non include un controllo previsto dalla personalizzazione, il metodo AddCustomization viene eseguito correttamente, tuttavia l'assembly non verrà caricato all'apertura del documento.

Il parametro fileType deve specificare un documento con l'estensione supportata per le personalizzazioni a livello di documento per Microsoft Office Word e Microsoft Office Excel. Non è possibile associare una personalizzazione a un documento salvato in formato Word XML Document (*xml) o Word 2003 XML Document (*xml). Per ulteriori informazioni sui tipi di file supportati, vedere Architettura delle personalizzazioni a livello di documento.

Esempi

Nell'esempio di codice seguente viene utilizzato il metodo AddCustomization per associare una personalizzazione al documento specificato.

Per questo esempio sono necessari i seguenti requisiti:

Progetto di applicazione console o qualche altro progetto non-Office.
Riferimenti ai seguenti assembly:
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll e Microsoft.VisualStudio.Tools.Applications.Runtime.dll (se il progetto è destinato a .NET Framework 4).
  
  oppure
- Microsoft.VisualStudio.Tools.Applications.ServerDocument.v10.0.dll e Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll (se il progetto è destinato a .NET Framework 3.5).

Private Sub AddCustomizationUsingAssemblyPath(ByVal documentPath As String, _
    ByVal assemblyName As String, ByVal solutionID As Guid, ByVal deployManifestPath As String)
    Dim runtimeVersion As Integer = 0

    Try
        ' Make sure that this document does not yet have any Visual Studio Tools 
        ' for Office customizations.
        runtimeVersion = ServerDocument.GetCustomizationVersion(documentPath)
        If runtimeVersion = 0 Then
            Dim deploymentManifestUri As New Uri(deployManifestPath)
            ServerDocument.AddCustomization(documentPath, assemblyName, solutionID, deploymentManifestUri)
            MessageBox.Show("The document was successfully customized.")
        Else
            System.Windows.Forms.MessageBox.Show("The document is already customized.")
        End If

    Catch ex As System.IO.FileNotFoundException
        System.Windows.Forms.MessageBox.Show("The specified document does not exist.")
    Catch ex As UnknownCustomizationFileException
        System.Windows.Forms.MessageBox.Show("The specified document has a file " & _
            "extension that is not supported by Visual Studio Tools for Office.")
    Catch ex As DocumentNotCustomizedException
        System.Windows.Forms.MessageBox.Show("The document could not be customized." & _
        vbLf & ex.Message)
    End Try
End Sub

private void AddCustomizationUsingAssemblyPath(string documentPath, string assemblyName, 
    Guid solutionID, string deployManifestPath)
{
    int runtimeVersion = 0;

    try
    {
        runtimeVersion = ServerDocument.GetCustomizationVersion(documentPath);

        // Make sure that this document does not yet have any Visual Studio Tools 
        // for Office customizations.
        if (runtimeVersion == 0)
        {
            Uri deploymentManifestUri = new Uri(deployManifestPath);
            ServerDocument.AddCustomization(documentPath, assemblyName, solutionID, deploymentManifestUri);
            MessageBox.Show("The document was successfully customized.");
        }
        else
        {
            System.Windows.Forms.MessageBox.Show("The document is already customized.");
        }
    }
    catch (System.IO.FileNotFoundException)
    {
        System.Windows.Forms.MessageBox.Show("The specified document does not exist.");
    }
    catch (UnknownCustomizationFileException)
    {
        System.Windows.Forms.MessageBox.Show("The specified document has a file " +
            "extension that is not supported by Visual Studio Tools for Office.");
    }
    catch (DocumentNotCustomizedException ex)
    {
        System.Windows.Forms.MessageBox.Show("The document could not be customized.\n" +
            ex.Message);
    }
}

Sicurezza di .NET Framework

Attendibilità totale per il chiamante immediato. Impossibile utilizzare questo membro in codice parzialmente attendibile. Per ulteriori informazioni, vedere Utilizzo di librerie da codice parzialmente attendibile.