Del via

Skriv en plug-in

  • Artikel

 

Udgivet: januar 2017

Gælder for: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Plug-ins er tilpassede klasser, der implementerer IPlugin-grænsefladen. Du kan skrive en plug-in på ethvert .NET Framework 4.5.2 CLR-kompatibelt sprog, f.eks. Microsoft Visual C# og Microsoft Visual Basic .NET. Hvis du vil kunne kompilere plug-in-kode, skal du føje Microsoft.Xrm.Sdk.dll og Microsoft.Crm.Sdk.Proxy.dll assembly-referencer til projektet. Disse assemblyer findes i mappen SDK\Bin i SDK.Hent SDK-pakken til Microsoft Dynamics CRM.

Dette emne indeholder

Plug-in-design

Skrivning af en grundlæggende plug-in

Skriv en plug-in-konstruktør

Understøttelse af kørsel offline

Webadgang for isolerede (sandkassekode) plug-ins

Brug tidligt bundne typer

Plug-in-assemblies

Plug-in-design

Plug-in-designet skal tage hensyn til webprogrammets funktion til automatisk lagring, der er indført i Microsoft Dynamics 365 (online og i det lokale miljø). Automatisk lagring er aktiveret som standard, men kan deaktiveres på organisationsniveau. Når den automatiske lagring er aktiveret, vises knappen Gem ikke. Webprogrammet gemmer automatisk data i formularen 30 sekunder efter den sidste ugemte ændring. Du kan anvende formularscripts til at deaktivere automatiske lagringsfunktioner på formularniveau. Afhængigt af hvordan du registrerede din plug-in, kan automatisk lagring resultere i, at din plug-in bliver kaldt oftere til individuelle feltændringer, i stedet for at plug-in-programmet aktiveres én gang for alle ændringer. Du skal antage, at enhver bruger kan gemme en post til enhver tid, uanset om det sker ved hjælp af Ctrl+S, ved at trykke på en Gem-knap eller automatisk via funktionen til automatisk lagring.

Den bedste fremgangsmåde er, at du registrerer din plug-in eller arbejdsprocessen for de objekter og felter, der betyder mest. Undgå at registrere en plug-in eller en arbejdsproces for ændringer af alle objektfelter. Hvis du har en eksisterende plug-in eller arbejdsproces, der blev implementeret, før funktionen til automatisk lagring blev tilgængelig, skal du igen teste den pågældende kode for at kontrollere, at den fungerer korrekt. Du kan finde flere oplysninger under TechNet: Administrering af automatisk lagring.

Skrivning af en grundlæggende plug-in

Følgende eksempel viser noget af den almindelige kode, der findes i en plug-in. I dette eksempel udelader koden enhver brugerdefineret forretningslogik, der ville udføre plug-in-programmets tilsigtede opgave. Koden viser dog en plug-in-klasse, der implementerer IPlugin-grænsefladen og den krævede Execute-metode.

using System;
using System.ServiceModel;
using Microsoft.Xrm.Sdk;

public class MyPlugin: IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        // Extract the tracing service for use in debugging sandboxed plug-ins.
        // If you are not registering the plug-in in the sandbox, then you do
        // not have to add any tracing service related code.
        ITracingService tracingService =
            (ITracingService)serviceProvider.GetService(typeof(ITracingService));

        // Obtain the execution context from the service provider.
        IPluginExecutionContext context = (IPluginExecutionContext)
            serviceProvider.GetService(typeof(IPluginExecutionContext));

        // The InputParameters collection contains all the data passed in the message request.
        if (context.InputParameters.Contains("Target") &&
            context.InputParameters["Target"] is Entity)
        {
            // Obtain the target entity from the input parameters.
            Entity entity = (Entity)context.InputParameters["Target"];

            // Verify that the target entity represents an entity type you are expecting. 
            // For example, an account. If not, the plug-in was not registered correctly.
            if (entity.LogicalName != "account")
                return;

            // Obtain the organization service reference which you will need for
            // web service calls.
            IOrganizationServiceFactory serviceFactory = 
                (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
            IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

            try
            {
                // Plug-in business logic goes here.
            }

            catch (FaultException<OrganizationServiceFault> ex)
            {
                throw new InvalidPluginExecutionException("An error occurred in MyPlug-in.", ex);
            }

            catch (Exception ex)
            {
                tracingService.Trace("MyPlugin: {0}", ex.ToString());
                throw;
            }
        }
    }
}

Parameteren IServiceProvider for Execute-metoden er en beholder til flere nyttige serviceobjekter, der kan åbnes i en plug-in. Tjenesteudbyderen indeholder forekomstreferencer til kørselskonteksten, IOrganizationServiceFactory, ITracingService og meget mere. Eksempelkoden viser, hvordan du kan hente referencer til kørselskonteksten, IOrganizationService og ITracingService fra tjenesteudbyderparameteren. Du kan finde oplysninger om sporingstjenesten under Fejlfinding af en plug-in.

Kørselskonteksten indeholder et væld af oplysninger om den hændelse, der forårsagede kørslen af denne plug-in, og de data, der er indeholdt i den meddelelse, der i øjeblikket behandles af pipelinen. Du kan finde flere oplysninger om datakonteksten under Forstå den datakontekst, der overføres til en plug-in.

Platformen viser de korrekte URL-adresser til webtjenester og legitimationsoplysninger til netværket, når du får organisationens webtjenestereference fra tjenesteudbyderen. Instantiering af din egen webtjenesteproxy understøttes ikke, da det resulterer i baglås og godkendelsesproblemer. Når du har organisationens tjenestereference, kan du bruge den til at foretage metodekald til organisationens webtjeneste. Du kan hente eller ændre virksomhedsdata i en enkelt Microsoft Dynamics 365-organisation ved at udstede en eller flere anmodninger om meddelelse til webtjenesten. Du kan finde flere oplysninger om meddelelsesanmodninger under Brug meddelelser (anmodnings- og svarklasser) med metoden Execute.

En typisk plug-in skal have adgang til oplysningerne i konteksten, udføre de nødvendige driftsrelaterede handlinger og håndtere undtagelser. Du kan finde flere oplysninger om håndtering af undtagelser i en plug-in under Håndtering af undtagelser i plug-ins. Et mere komplet plug-in-eksempel findes i emnet Eksempel: Oprette en grundlæggende plug-in.

Vigtigt

For at forbedre ydeevnen cachelagrer Microsoft Dynamics 365 plug-in-forekomster. Plug-in-programmets Execute-metode skal skrives for at være tilstandsløs, fordi konstruktøren ikke kaldes for hver aktivering af plug-in-programmet. Desuden kunne flere tråde i systemet køre plug-in-programmet på samme tid. Alle tilstandsoplysninger pr. aktivering gemmes i konteksten, så du bør ikke bruge globale variabler eller forsøge at gemme data i medlemsvariabler til brug under den næste plug-in-aktivering, medmindre disse data blev hentet fra konfigurationsparameteren til konstruktøren. Ændringer i registreringen af en plug-in vil medføre, at plug-in-programmet initialiseres igen.

Skriv en plug-in-konstruktør

Microsoft Dynamics 365-platformen understøtter en valgfri plug-in-konstruktør, som accepterer enten en eller to strengparametre. Hvis du skriver en konstruktør som denne, kan du overføre enhver streng med oplysninger til plug-in-programmet på kørselstidspunktet.

Følgende eksempel viser formatet for konstruktøren. I dette eksempel har plug-in-klassen navnet SamplePlugin.

public SamplePlugin()
public SamplePlugin(string unsecure)
public SamplePlugin(string unsecure, string secure)

Den første strengparameter for konstruktøren indeholder offentlige (usikre) oplysninger. Den anden strengparameteren indeholder ikke-offentlige (sikre) oplysninger. I denne beskrivelse refererer sikker til en krypteret værdi, mens usikker er en ikke-krypteret værdi. Når du bruger Microsoft Dynamics 365 til Microsoft Office Outlook med offlineadgang, overføres den sikre streng ikke til en plug-in, der kører, mens Dynamics 365 til Outlook er offline.

De oplysninger, der sendes til plug-in-konstruktøren i disse strenge, angives, når plug-in-programmet registreres i Microsoft Dynamics 365. Når du bruger værktøjet til registrering af plug-ins til at registrere en plug-in, kan du angive sikre og usikre oplysninger i felterne Sikker konfiguration og Usikker konfiguration, der findes i formularen Registrer nyt trin. Når du registrerer en plug-in via programmering ved hjælp af Microsoft Dynamics 365-SDK, indeholder SdkMessageProcessingStep.Configuration den usikre værdi, og SdkMessageProcessingStep.SecureConfigId refererer til en SdkMessageProcessingStepSecureConfig-post, der indeholder den sikre værdi.

Understøttelse af kørsel offline

Du kan registrere, at plug-ins skal køres i onlinetilstand, offlinetilstand eller begge dele. Offlinetilstand understøttes kun i Microsoft Dynamics 365 til Microsoft Office Outlook med offlineadgang. Din plug-in-kode kan kontrollere, om den kører i offlinetilstand, ved at kontrollere egenskaben IsExecutingOffline.

Når du designer en plug-in, der bliver registreret til kørsel både online og offline, skal du huske, at plug-in-programmet kan køre to gange. Første gang er, når Microsoft Dynamics 365 til Microsoft Office Outlook med offlineadgang er offline. Plug-in-programmet kører igen, når Dynamics 365 til Outlook går online, og Dynamics 365 til Outlook og Microsoft Dynamics 365-serveren synkroniseres. Du kan kontrollere egenskaben IsOfflinePlayback for at bestemme, om plug-in-programmet kører på grund af denne synkronisering.

Webadgang for isolerede (sandkassekode) plug-ins

Hvis du vil registrere din plug-in i sandkassen, kan du stadig få adgang til webadresser fra din plug-in-kode. Du kan bruge enhver .NET Framework-klasse i plug-in-koden, som giver adgang til internettet, inden for de webadgangsbegrænsninger, der er beskrevet i Plug-in-isolation, -tillidsforhold og -statistik. For eksempel downloader følgende plug-in-kode en webside.


// Download the target URI using a Web client. Any .NET class that uses the
// HTTP or HTTPS protocols and a DNS lookup should work.
using (WebClient client = new WebClient())
{
    byte[] responseBytes = client.DownloadData(webAddress);
    string response = Encoding.UTF8.GetString(responseBytes);
System_CAPS_security Sikkerhed Bemærkning

Når sandkassekodede plug-ins skal kunne få adgang til eksterne webtjenester, skal den server, hvor rollen for sandkassebehandlingstjenesten er installeret, være tilgængelig fra internettet, og den konto, som sandkassebehandlingstjenesten kører under, skal have adgang til internettet. Der kræves kun udgående forbindelser på portene 80 og 443. Der kræves ikke indgående forbindelsesadgang. Brug kontrolpanelet for Windows Firewall til at aktivere udgående forbindelser for det Microsoft.Crm.Sandbox.WorkerProcess-program, der er placeret på serveren i mappen %PROGRAMFILES%\Microsoft Dynamics 365\Server\bin.

Brug tidligt bundne typer

Når du vil bruge tidligt bundne Microsoft Dynamics 365-typer i plug-in-kode, skal du blot medtage filen for typen, der er oprettet ved hjælp af programmet CrmSvcUtil, i dit Microsoft Visual Studio-plug-in-projekt.

Konvertering af et sent bundet objekt til et tidligt bundet objekt gøres på følgende måde:

Account acct = entity.ToEntity<Account>();

I den forrige kodelinje er variablen acct et tidligt bundet type. Alle Entity-værdier, der er tildelt IPluginExecutionContext, skal være sent bundne typer. Hvis der er tildelt en tidligt bundet type til konteksten, opstår der en SerializationException. Du kan finde flere oplysninger under Forstå den datakontekst, der overføres til en plug-in. Sørg for ikke at blande dine typer, og brug en tidligt bundet type, hvor et sent bundet type kaldes, som vist i følgende kode.

context.InputParameters["Target"] = new Account() { Name = "MyAccount" }; // WRONG: Do not do this.

I ovenstående eksempel skal du ikke gemme en tidligt bundet forekomst i plug-in-konteksten, hvor der skal være en sent bundet forekomst. Dette er for at undgå, at platformen skal konvertere mellem tidligt bundne og sent bundne typer før kald af en plug-in, og når der vendes tilbage fra plug-in-programmet til platformen.

Plug-in-assemblies

En assembly kan indeholde en eller flere plug-in-typer. Når plug-in-assemblyen er registreret og installeret, kan plug-ins udføre den tilsigtede handling som svar på en kørselshændelse i Microsoft Dynamics 365.

System_CAPS_security Sikkerhed Bemærkning

I Microsoft Dynamics 365 skal plug-in-assemblyer kunne læses af alle for at fungere korrekt. Af sikkerhedsmæssige årsager er det derfor den bedste fremgangsmåde at udvikle plug-in-kode, der ikke indeholder nogen oplysninger om systemlogon, fortrolige oplysninger eller forretningshemmeligheder.

Hver plug-in-assembly skal signeres, enten under fanen Signing (Signering) i projektets egenskabsark i Microsoft Visual Studio eller med værktøjet sikkert navn, før den registreres og installeres i Microsoft Dynamics 365. Du kan finde flere oplysninger om værktøjet sikkert navn ved at køre programmet sn.exe uden argumenter fra et kommandopromptvindue i Microsoft Visual Studio.

Hvis din assembly indeholder en plug-in, der kan køres, mens Dynamics 365 til Outlook er offline, er der endnu bedre sikkerhed for, at Microsoft Dynamics 365-platformen anvender assemblyer. Du kan finde flere oplysninger under Gennemgang: Konfigurere assembly-sikkerhed for en offline plug-in.

Se også

Plug-in-udvikling
Forstå den datakontekst, der overføres til en plug-in
Skriv en brugerdefineret Azure-følsom plug-in
Registrere og installere plug-ins
Håndtering af undtagelser i plug-ins
Eksempel: Oprette en grundlæggende plug-in
Eksempel: Webadgang fra en sandkasse-plug-in
Køre værktøjet til oprettelse af kode
Blog: Brug plugins til at Ændre visninger

Microsoft Dynamics 365

© 2017 Microsoft. Alle rettigheder forbeholdes. Ophavsret