Een invoegtoepassing schrijven
Gepubliceerd: november 2016
Is van toepassing op: Dynamics CRM 2015
Invoegtoepassingen zijn aangepaste klassen die de IPlugin-interface implementeren. U kunt een invoegtoepassing schrijven in elke .NET Framework 4.5.2 CLR-taal zoals Microsoft Visual C# en Microsoft Visual Basic .NET. Als u invoegcode wilt kunnen compileren, moet u Microsoft.Xrm.Sdk.dll- en Microsoft.Crm.Sdk.Proxy.dll-assemblyverwijzingen aan uw project toevoegen. Deze assembly's zijn te vinden in de map SDK\Bin van de SDK.Download het Microsoft Dynamics CRM SDK-pakket.
In dit onderwerp
Ontwerp van invoegtoepassingen
Een basisinvoegtoepassing schrijven
Een constructor voor een invoegtoepassing schrijven
Offline uitvoering ondersteunen
Webtoegang voor geïsoleerde (sandboxed) invoegtoepassingen
Eerder gebonden typen gebruiken
Invoegtoepassingassembly's
Ontwerp van invoegtoepassingen
Bij het ontwerp van uw invoegtoepassing moet u rekening houden met de functie automatisch opslaan van de webtoepassing, die is geïntroduceerd in Microsoft Dynamics CRM 2015 en Microsoft Dynamics CRM Online 2015 Update. Automatisch opslaan is standaard ingeschakeld, maar kan op organisatieniveau worden uitgeschakeld. Als automatisch opslaan is ingeschakeld, is er geen knop Opslaan. De webtoepassing slaat gegevens in het formulier automatisch 30 seconden na de laatste niet-opgeslagen wijziging op. U kunt formulierscripts toepassen om de werking van automatisch opslaan op formulierniveau uit te schakelen. Afhankelijk van de manier waarop u de invoegtoepassing hebt geregistreerd, kan automatisch opslaan ertoe leiden dat uw invoegtoepassing vaker voor afzonderlijke veldwijzigingen wordt aangeroepen, in plaats van dat de invoegtoepassing eenmaal wordt aangeroepen voor alle wijzigingen. U moet aannemen dat elke gebruiker alle records op elk moment kan opslaan, hetzij met Ctrl+S of door op de knop Opslaan te drukken, hetzij automatisch met de functie automatisch opslaan.
Het verdient aanbeveling om uw invoegtoepassing of werkstroom te registreren voor entiteiten en specifieke velden die het belangrijkst zijn. Registreer een invoegtoepassing of werkstroom niet voor wijzigingen in alle entiteitvelden. Als u een bestaande invoegtoepassing of werkstroom hebt die is geïmplementeerd voordat de functie automatisch opslaan beschikbaar was, moet u de code opnieuw testen om te kijken of deze goed werkt. Raadpleeg TechNet: Automatisch opslaan beheren voor meer informatie.
Een basisinvoegtoepassing schrijven
Dit voorbeeld toont code die veel voorkomt in invoegtoepassingen. In dit voorbeeld is aangepaste bedrijfslogica weggelaten die de bedoelde taak van de invoegtoepassing zou uitvoeren. De code toont echter wel een invoegklasse die de IPlugin-interface implementeert, en de vereiste Execute-methode.
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;
}
}
}
}
De parameter IServiceProvider van de methode Execute is een container voor verschillende nuttige objecten waartoe binnen een invoegtoepassing toegang kan worden verkregen. De serviceprovider bevat exemplaarverwijzingen naar de uitvoeringscontext, IOrganizationServiceFactory, ITracingService, en meer. De voorbeeldcode geeft aan hoe verwijzingen naar de uitvoeringscontext, IOrganizationService en ITracingService worden verkregen vanuit de serviceproviderparameter. Voor meer informatie over de traceringsservice raadpleegt u Fouten opsporten in een invoegtoepassing.
De uitvoeringscontext bevat een schat aan nuttige informatie over de gebeurtenis die de uitvoering van de invoegtoepassing heeft veroorzaakt en de gegevens in het bericht dat momenteel door de pipeline wordt verwerkt. Voor meer informatie over de gegevenscontext raadpleegt u Begrijp de gegevenscontext in een plug-in.
Het platform biedt de juiste webservice-URL's en netwerkreferenties wanneer u de verwijzing naar de organisatiewebservice verkrijgt van de serviceprovider. Het maken van een exemplaar van uw eigen webserviceproxy wordt niet ondersteund omdat het leidt tot een impasse en tot verificatieproblemen. Nadat u de verwijzing naar de organisatieservice hebt gemaakt, kunt u deze gebruiken om methodeaanroepen te doen naar de organisatiewebservice. U kunt bedrijfsgegevens in één Microsoft Dynamics 365-organisatie ophalen of wijzigen door een of meer berichtaanvragen aan de webservice uit te voeren. Voor meer informatie over berichtaanvragen raadpleegt u Berichten (aanvraag- en responsklassen) gebruiken met de methode Execute.
Een typische invoegtoepassing moet toegang tot de gegevens in de context hebben, de bedrijfsactiviteiten uitvoeren en uitzonderingen afhandelen. Voor meer informatie over het afhandelen van uitzonderingen in een invoegtoepassing raadpleegt u Uitzonderingen in invoegtoepassingen afhandelen. Een vollediger voorbeeld van een invoegtoepassing is beschikbaar in het onderwerp Voorbeeld: een basisinvoegtoepassing maken.
Belangrijk
Voor betere prestaties plaatst Microsoft Dynamics 365 invoegexemplaren in een cache. De methode Execute van de invoegtoepassing moet stateless worden geschreven omdat de constructor niet voor elke aanroep van de invoegtoepassing wordt aangeroepen. Ook kunnen meerdere systeemthreads de invoegtoepassing tegelijkertijd uitvoeren. Alle statusinformatie per aanroep wordt opgeslagen in de context. U moet dus geen globale variabelen gebruiken of proberen gegevens op te slaan in lidvariabelen voor gebruik tijdens de volgende aanroep van de invoegtoepassing, tenzij die gegevens zijn verkregen van de configuratieparameter die is verschaft aan de constructor. Wijzigingen in de registratie van een invoegtoepassing leiden ertoe dat de invoegtoepassing opnieuw wordt geïnitialiseerd.
Een constructor voor een invoegtoepassing schrijven
Het Microsoft Dynamics 365-platform ondersteunt een optionele constructor voor een invoegtoepassing die een van twee tekenreeksparameters accepteert. Als u een constructor zo schrijft, kunt u tijdens de uitvoering tekenreeksen met informatie aan de invoegtoepassing doorgeven.
Het volgende voorbeeld toont de notatie van de constructor. In dit voorbeeld heet de invoegtoepassingsklasse SamplePlugin.
public SamplePlugin()
public SamplePlugin(string unsecure)
public SamplePlugin(string unsecure, string secure)
De eerste tekenreeksparameter van de constructor bevat openbare (onbeveiligde) informatie. De tweede tekenreeksparameter bevat niet-openbare (beveiligde) informatie. In deze bespreking verwijst beveiligd naar een versleutelde waarde en verwijst onbeveiligd naar een niet-versleutelde waarde. Wanneer Microsoft Dynamics CRM voor Microsoft Office Outlook met offlinetoegang wordt gebruikt, wordt de beveiligde tekenreeks niet doorgegeven aan een invoegtoepassing die wordt uitgevoerd terwijl Dynamics CRM voor Outlook offline is.
De informatie die in deze tekenreeksen wordt doorgegeven aan de constructor van de invoegtoepassing, wordt opgegeven met Microsoft Dynamics 365. Wanneer u het hulpmiddel voor invoegtoepassingsregistratie gebruikt om een invoegtoepassing te registreren, kunt u beveiligde en onbeveiligde informatie invoeren in de velden Beveiligingsconfiguratie en Onbeveiligde informatie op het formulier Nieuwe stap registreren. Wanneer u een invoegtoepassing dor middel van programmering registreert met Microsoft Dynamics CRM SDK, bevat SdkMessageProcessingStep.SecureConfigId de onbeveiligde waarde en verwijst SdkMessageProcessingStep.Configuration naar een SdkMessageProcessingStepSecureConfig-record die de beveiligde waarde bevat.
Offline uitvoering ondersteunen
U kunt invoegtoepassingen registreren voor uitvoering in de onlinemodus, de offlinemodus of beide. De offlinemodus wordt alleen ondersteund op Microsoft Dynamics CRM voor Microsoft Office Outlook met offlinetoegang. Uw invoegcode kan controleren of deze in de offlinemodus wordt uitgevoerd door de eigenschap IsExecutingOffline te controleren.
Als u een invoegtoepassing ontwerpt die wordt geregistreerd voor zowel online- als offline-uitvoering, moet u er rekening mee houden dat de invoegtoepassing tweemaal kan worden uitgevoerd. De eerste keer is terwijl Microsoft Dynamics CRM voor Microsoft Office Outlook met offlinetoegang offline is. De invoegtoepassing wordt opnieuw uitgevoerd als Dynamics CRM voor Outlook online gaat en de synchronisatie tussen Dynamics CRM voor Outlook en de Microsoft Dynamics 365-server optreedt. U kunt de eigenschap IsOfflinePlayback controleren om na te gaan of de invoegtoepassing vanwege deze synchronisatie wordt uitgevoerd.
Webtoegang voor geïsoleerde (sandboxed) invoegtoepassingen
Als u uw invoegtoepassing in de sandbox gaat registreren, kunt u toch toegang tot webadressen krijgen vanuit uw invoegcode. U kunt elke .NET Framework-klasse in uw invoegcode gebruiken die webtoegang biedt binnen de beschreven beperkingen van webtoegang Isolatie, trusts en statistieken van invoegtoepassingen. De volgende invoegcode downloadt bijvoorbeeld een webpagina.
// 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);
.jpeg "System_CAPS_security") Beveiliging Opmerking |
|---|
Als sandboxed invoegtoepassingen toegang moeten hebben tot externe webservices, moet de server waar de sandboxverwerkingsservice is geïnstalleerd, verbinding met internet hebben en moet het account waaronder de sandboxservice werkt, internettoegang hebben. Alleen uitgaande verbindingen op poorten 80 en 443 zijn vereist. Toegang tot binnenkomende verbindingen is niet vereist. Gebruik het bedieningspaneel van Windows Firewall om uitgaande verbindingen in te schakelen voor de Microsoft.Crm.Sandbox.WorkerProcess-toepassing die zich op de server bevindt in de map %PROGRAMFILES%\Microsoft Dynamics CRM\Server\bin. |
Eerder gebonden typen gebruiken
Als u eerder gebonden Microsoft Dynamics 365-typen in uw invoegcode wilt gebruiken, neemt u het typebestand dat wordt genegeerd met het CrmSvcUtil-programma, in uw Microsoft Visual Studio-invoegproject op.
Conversie van een later gebonden entiteit naar een eerder gebonden entiteit wordt als volgt afgehandeld:
Account acct = entity.ToEntity<Account>();
In de voorafgaande coderegel, is de variabele acct een eerder gebonden type. Alle Entity-waarden die aan IPluginExecutionContext worden toegewezen, moeten later gebonden typen zijn. Als een eerder gebonden type aan de context wordt toegewezen, treedt een SerializationException op. Zie Begrijp de gegevenscontext in een plug-in voor meer informatie. Zorg ervoor dat u de typen niet combineert en dat u geen eerder gebonden type gebruikt als een later gebonden type nodig is, zoals in de volgende code.
context.InputParameters["Target"] = new Account() { Name = "MyAccount" }; // WRONG: Do not do this.
In het bovenstaande voorbeeld wilt u een eerder gebonden exemplaar opslaan in de invoegcontext waar het een later gebonden exemplaar moet zijn. Dat is om te voorkomen dat het platform moet converteren tussen eerder en later gebonden typen voordat een invoegtoepassing wordt aangeroepen en wanneer wordt teruggekeerd van de invoegtoepassing naar het platform.
Invoegtoepassingassembly's
Een assembly kan een of meer typen invoegtoepassingen bevatten. Nadat de invoegtoepassingassembly is geregistreerd en geïmplementeerd, kunnen invoegtoepassingen hun bedoelde werking vertonen in reactie op een Microsoft Dynamics 365 runtime gebeurtenis.
| Beveiliging Opmerking |
|---|
In Microsoft Dynamics 365 moeten de invoegtoepassingsassembly's leesbaar zijn voor iedereen om goed te kunnen functioneren. Het wordt daarom om beveiligingsredenen aanbevolen invoegcode te ontwikkelen die geen aanmeldingsgegevens voor het systeem, vertrouwelijke informatie of bedrijfsgeheimen bevat. |
Elke invoegtoepassingassembly moet zijn ondertekend, of via het tabblad Ondertekening van het eigenschappenblad van het project in Microsoft Visual Studio of met het hulpprogramma Strong Name, voordat het kan worden geregistreerd en geïmplementeerd naar Microsoft Dynamics 365. Voor meer informatie over het hulpprogramma Strong Name voert u het programma sn.exe zonder argumenten uit vanuit een Microsoft Visual Studio opdrachtpromptvenster.
Als uw assembly een invoegtoepassing bevat die kan worden uitgevoerd terwijl Dynamics CRM voor Outlook offline is, is er extra beveiliging die het Microsoft Dynamics 365-platform oplegt aan assembly's. Zie Overzicht: Configureer assemblybeveiliging voor een offline plug-in voor meer informatie.
Zie ook
Ontwikkeling van plug-ins
Begrijp de gegevenscontext in een plug-in
Een aangepaste Azure-bewuste invoegtoepassing schrijven
Plug-ins registreren en inzetten
Uitzonderingen in invoegtoepassingen afhandelen
Voorbeeld: een basisinvoegtoepassing maken
Voorbeeld: Webtoegang vanuit een invoegtoepassing in de sandbox
Het hulpprogramma voor het genereren van code uitvoeren
Blog: Invoegtoepassingen gebruiken om weergaven te wijzigen
© 2017 Microsoft. Alle rechten voorbehouden. Auteursrecht